使用 Python Sphinx 向模块文档字符串添加参数
Adding parameters to module docstrings with Python Sphinx
我在每个模块的开头都有一个文档字符串来描述它的用法和功能。在这里我还想添加最相关的参数——比如参数文件中的设置或通过命令行参数。它不是经典的函数参数，因为模块也可能被称为 stand-alone（通过 if __name__ == '__main__' 捕获）。但是由于 Sphinx 的普通参数格式很整洁，我只想 re-use 它。
但是，Sphinx 在模块中和在函数中处理 “参数”部分 的方式似乎不同。
它们的格式不同：
函数文档字符串中的参数：
模块文档字符串中的参数：
你看到区别了。在函数中添加了关键字 "Parameters"，然后我们就有了一个不错的项目符号列表。在模块中没有创建标题，没有列表，类型没有设置在大括号中而是在附加行等。
文档字符串格式相同 (numpydoc):
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).
有人知道为什么要这样处理吗？我能做些什么？
我希望模块中的参数输出与函数中的参数相同。
用于呈现您与 Sphinx 一起使用的 docstring sections is dependent on the HTML theme 的样式。
Does anyone have an idea why it's handled like this?
模块和函数文档字符串的样式不同的原因是，习惯上使用 command-line 语法 样式来记录不同于 函数签名语法风格。请注意，您为模块文档字符串显示的样式类似于 command-line 个参数列表。
I would like the parameters in modules output in the same way as in functions.
不同的主题可能会以与函数和类文档字符串相似或不同的方式呈现模块文档字符串。您必须选择不同的主题或通过将用于函数的样式复制到用于模块文档字符串的样式来自定义主题的 CSS。
the type is not set in braces but on an additional line etc.
这是值得注意的，因为您会期望 napoleon-sphinx extension 不会在不同的行上呈现类型和名称，就像它使用经典的 reST 语法而不是 Google 样式或 Numpy 一样。
我建议尝试不同的 HTML 主题或明确设置 napoleon_use_param , napoleon_use_ivar and napoleon_use_rtype 以查看是否存在差异。
And what I can do about it?
为 Google style or Numpy style suggest using docstring sections but that's somewhat oversimplified because command-line style syntax is better illustrated and automated by the way argparse implements it. There are a few extensions 提供的示例旨在简化和自动化记录脚本的过程。
至于风格上的差异，我不担心（诚然，在您当前使用的 HTML 主题中，它看起来不太好）。脚本的 command-line 调用或函数的 run-time 调用是不同的，因此主题可能并且将呈现具有视觉差异的文档字符串部分。
我在每个模块的开头都有一个文档字符串来描述它的用法和功能。在这里我还想添加最相关的参数——比如参数文件中的设置或通过命令行参数。它不是经典的函数参数，因为模块也可能被称为 stand-alone（通过 if __name__ == '__main__' 捕获）。但是由于 Sphinx 的普通参数格式很整洁，我只想 re-use 它。
但是，Sphinx 在模块中和在函数中处理 “参数”部分 的方式似乎不同。
它们的格式不同：
函数文档字符串中的参数：
模块文档字符串中的参数：
你看到区别了。在函数中添加了关键字 "Parameters"，然后我们就有了一个不错的项目符号列表。在模块中没有创建标题，没有列表，类型没有设置在大括号中而是在附加行等。
文档字符串格式相同 (numpydoc):
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).
有人知道为什么要这样处理吗？我能做些什么？
我希望模块中的参数输出与函数中的参数相同。
用于呈现您与 Sphinx 一起使用的 docstring sections is dependent on the HTML theme 的样式。
Does anyone have an idea why it's handled like this?
模块和函数文档字符串的样式不同的原因是，习惯上使用 command-line 语法 样式来记录不同于 函数签名语法风格。请注意，您为模块文档字符串显示的样式类似于 command-line 个参数列表。
I would like the parameters in modules output in the same way as in functions.
不同的主题可能会以与函数和类文档字符串相似或不同的方式呈现模块文档字符串。您必须选择不同的主题或通过将用于函数的样式复制到用于模块文档字符串的样式来自定义主题的 CSS。
the type is not set in braces but on an additional line etc.
这是值得注意的，因为您会期望 napoleon-sphinx extension 不会在不同的行上呈现类型和名称，就像它使用经典的 reST 语法而不是 Google 样式或 Numpy 一样。
我建议尝试不同的 HTML 主题或明确设置 napoleon_use_param , napoleon_use_ivar and napoleon_use_rtype 以查看是否存在差异。
And what I can do about it?
为 Google style or Numpy style suggest using docstring sections but that's somewhat oversimplified because command-line style syntax is better illustrated and automated by the way argparse implements it. There are a few extensions 提供的示例旨在简化和自动化记录脚本的过程。
至于风格上的差异，我不担心（诚然，在您当前使用的 HTML 主题中，它看起来不太好）。脚本的 command-line 调用或函数的 run-time 调用是不同的，因此主题可能并且将呈现具有视觉差异的文档字符串部分。