使用Python Sphinx向模块docstring添加参数

我在每个模块的开头都有一个文档字符串，描述其用法和功能。在这里，我还想在参数文件中或通过命令行参数添加最相关的参数，如设置。它不是经典的函数参数，因为模块也可以作为独立函数调用（通过

if\uuuuuu name\uuuuu=='\uuuuuu main\uuuu'

capture）。但是由于Sphinx的普通参数格式很简洁，我只想重复使用它

然而，Sphinx在模块中处理“参数”部分的方式似乎与在函数中处理“参数”部分的方式不同

这就是它们的不同格式：

函数docstring中的参数：

模块docstring中的参数：

你看到了区别。在函数中添加了关键字“Parameters”，然后我们有了一个很好的项目符号列表。在模块中，没有创建标题，没有列表，类型没有在大括号中设置，而是在附加行中设置，等等

Docstring格式相同（numpydoc）：

vs

有人知道为什么会这样处理吗？我能做些什么呢

---

我希望模块中的参数以与函数中相同的方式输出。

用于渲染的样式取决于您在Sphinx中使用的样式

有人知道为什么会这样处理吗

模块和函数docstring的样式不同的原因是，通常使用命令行语法样式来记录与函数签名语法样式不同的脚本。请注意，您为模块docstring显示的样式类似于命令行参数列表

我希望模块中的参数以与函数中相同的方式输出

不同的主题可能呈现与函数和类docstring类似或不同的模块docstring。您必须选择不同的主题，或者通过将用于函数的样式复制到用于模块docstring的样式来自定义主题的CSS

该类型不是在大括号中设置的，而是在附加行中设置的

这是值得注意的，因为您希望不会在不同的行上呈现类型和名称，就像它使用经典的reST语法而不是Google样式或Numpy一样

我建议尝试不同的HTML主题或设置，并明确地查看是否有差异

我能做些什么呢

给出的示例或建议使用docstring部分，但这有点过于简单，因为命令行样式的语法在实现它的方式上得到了更好的说明和自动化。它们旨在简化和自动化脚本的文档化过程

---

至于风格上的差异，我并不担心（无可否认，在您当前使用的HTML主题中，它看起来不是很好）。脚本的命令行调用或函数的运行时调用是不同的，因此主题可能并将呈现具有视觉差异的那些docstring部分。

非常感谢您提供的详细信息！现在我明白了不同格式背后的原因（尽管我仍然不喜欢它们）。最后，拿破仑成功了。

Parameters
----------
pars : dict
    Parameter dictionary.
key : str
    Parameter name.

Parameters
----------
num_axial_segments : int
    The number of axial rotor segments.
magnet_segmentation_method : int
    The method of magnet segmentation.
    0: Uniform segmentation (all magnets same amount of segments).