狮身人面像自动文档替换标准：成员：答案

【问题标题】：Sphinx autodoc replace standard :members:狮身人面像自动文档替换标准：成员：
【发布时间】：2014-05-05 05:39:27
【问题描述】：

所以我决定做这样的事情：

我需要

.. automodule:: main
   :members:

但具有以下功能

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

.. autodata:: CAPTION

   About my caption

所以，我需要为每个函数、方法和类写一些东西，但同时我还需要我在代码中创建的所有新函数都将出现在文档中，而无需编辑文档。有可能吗？

【问题讨论】：

【解决方案1】：

来自docs：

没有文档字符串的成员将被排除在外，除非您提供 undoc-members 标志选项：

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

此外，如果给出了 private-members 标志选项，“私有”成员（即命名为 _private 或 __private）将被包括在内，并且 Python“特殊”成员（即，命名为 __special__ 的那些）将被包括在内如果给出了特殊成员标志选项：

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

最后！可以使用常规语法覆盖显式记录的可调用对象（函数、方法、类）的签名，这将覆盖从自省获得的签名：

.. autoclass:: Noodle(type)

   .. automethod:: eat(persona)

我在答案开头发布的链接中有很多有用的信息。查看它，了解更高级的代码记录方法。

【讨论】：

已经把这个页面倒过来读了 10 次，以及 sphinx wiki 上的其他页面 + 大量的 stackoverflow 线程 :) 也许我问错了，我想做的是使用 :members: (和也许 :undoc-members :) 这样当我向我的项目添加代码时 - 它会出现在 sphinx-documentation 中而不受我的干扰。但我还需要能够为每个类/函数/变量添加一些信息，因为我喜欢没有 cmets 的干净代码，而且我的项目中几乎没有文档字符串。
另外，我刚刚注意到我在方法中的所有变量都被 sphinx 完全忽略了......这有点奇怪和糟糕，因为我有一个类和很多函数，其中包含重要的周期和变量
如果你是唯一一个阅读你的代码的人，那么没有文档字符串可能是可以的，但实际上这是一种不好的做法。许多程序员首先阅读代码，然后阅读文档，因此请考虑至少拥有一些基本的文档字符串，这些文档字符串至少可以描述这件事正在做什么，当然要避免显而易见。此外， :members: 和 :undoc-members: 将完全按照您的意愿行事。如果这对您不起作用，您在其他地方遇到问题，您在生成文档时是否遇到任何错误？此外，Sphinx 不会记录您的循环和函数内的其他逻辑，只是它的签名。

【解决方案2】：

当我四处寻找解决方案时，我偶然发现了这个问题。

我不确定它是否是您正在寻找的东西，但它解决了我的问题，并且它包含在此处以供任何可能觉得它有用的人Github HyperSpy Repo

有一个不错的小 bash 脚本，可以筛选代码并编写正确的代码

.. automodule

对于源代码树中的每个模块，希望对您有所帮助

【讨论】：