Sphinx自动文档替换标准:members:

Question

我想做一个这样的东西：

我需要

.. automodule:: main
   :members:

但是要有

This is my caption
------------------

.. autodata:: CAPTION

   About my caption

所以，我需要为每个功能、方法和类写一些说明，但同时我希望我在代码中创建的所有新功能都能自动出现在文档里，而不需要手动去编辑文档。这可能吗？

Answer 1

我在寻找一个方法，把我代码里的所有模块、方法和函数都包含到文档里时，偶然发现了这个问题。

我不确定这是否正是你想要的，但它解决了我的问题，所以我把它放在这里，供可能需要的人参考。你可以在这个Github HyperSpy 仓库找到它。

里面有一个很不错的bash脚本，它会扫描你的代码，并为每个模块生成合适的文档。

.. automodule

希望这对你有帮助。

Answer 2

来自文档：

如果成员没有文档字符串（docstring），那么它们将不会被包含在内，除非你使用了undoc-members这个选项：

.. automodule:: noodle
   :members:
   :undoc-members:

另外，如果你使用了private-members这个选项，那么“私有”成员（也就是那些名字以_private或__private开头的）会被包含在内；如果你使用了special-members这个选项，那么Python的“特殊”成员（名字以__special__开头的）也会被包含在内：

.. autoclass:: my.Class
   :members:
   :private-members:
   :special-members:

最后！你可以用常规语法来覆盖那些已经明确记录的可调用对象（比如函数、方法、类）的签名，这样就可以替代通过反射获得的签名：

.. autoclass:: Noodle(type)

   .. automethod:: eat(persona)

在我一开始提到的链接中还有很多有用的信息。可以去看看，了解更多高级的代码文档写法。