使用Python Sphinx将参数添加到模块文档字符串中

如何解决使用Python Sphinx将参数添加到模块文档字符串中

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

但是，与在函数中时相比，Sphinx在模块中处理“参数”部分的方式似乎有所不同。

这是它们的格式不同：

函数docstring中的参数：

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

您看到了区别。在函数中添加了关键字“ Parameters” ，然后我们有了一个漂亮的项目符号列表。在模块中，不创建标题，不创建列表，不将其类型设置为大括号，而是在其他行上设置。

文档字符串格式相同（numpydoc）：

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

vs。

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).

有人知道为什么要这样处理吗？那我该怎么办？

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

解决方法

用于渲染docstring sections的样式取决于您在Sphinx中使用的HTML theme。

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

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

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

不同的主题可以使模块文档字符串与功能文档和类文档字符串相似或不同。您将不得不选择其他主题或通过将用于函数的样式复制到用于模块文档字符串的样式来定制主题的CSS。

类型不是用大括号设置的，而是用其他行表示的。

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

我建议尝试使用其他HTML主题或明确设置napoleon_use_param，napoleon_use_ivar和napoleon_use_rtype来查看是否存在差异。

那我该怎么办？

为Google style或Numpy style给出的示例建议使用docstring节，但这在某种程度上被简化了，因为通过argparse的实现方式可以更好地说明和自动化命令行样式的语法。 a few extensions旨在简化和自动化文档编写脚本的过程。

关于样式的差异，我不会担心（公认的是，您当前使用的HTML主题看起来不太好）。脚本的命令行调用或函数的运行时调用是不同的，因此主题可能并且将使这些文档字符串部分具有视觉差异。