python - 使用 Python Sphinx 向模块文档字符串添加参数

Question

我在每个模块的开头都有一个文档字符串，描述了它的用法和功能。在这里，我还想添加最相关的参数 - 例如参数文件中的设置或通过命令行参数。它不是经典的函数参数，因为模块也可能被称为独立的（通过if __name__ == '__main__'捕获）。但是由于 Sphinx 的普通参数格式很整洁，我想重新使用它。

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

这就是它们的不同格式：

函数文档字符串中的参数：

模块文档字符串中的参数：

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

文档字符串格式相同（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).

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

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

标签： pythoncommand-line-argumentspython-sphinxdocstringsphinx-napoleon

Answer 1

用于呈现文档字符串部分的样式取决于您与 Sphinx 一起使用的HTML 主题。

有谁知道为什么会这样处理？

模块和函数文档字符串的样式不同的原因是，习惯上使用命令行语法样式来记录与函数签名语法样式不同的脚本。请注意，您为模块文档字符串显示的样式类似于命令行参数列表。

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

不同的主题可能会以与函数和类文档字符串相似或不同的方式呈现模块文档字符串。您必须选择不同的主题或通过将用于函数的样式复制到用于模块文档字符串的样式来自定义主题的 CSS。

类型未设置在大括号中，而是设置在附加行等上。

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

我建议尝试不同的 HTML 主题或设置napoleon_use_param,napoleon_use_ivar并napoleon_use_rtype明确查看是否有区别。

我能做些什么呢？

为Google 样式或Numpy 样式给出的示例建议使用 docstring 部分，但这有点过于简单，因为命令行样式语法通过实现方式更好地说明和自动化argparse。有一些扩展旨在简化和自动化记录脚本的过程。

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