python - Sphinx 不处理 python 类

Question

再见， 我在自动生成 python 文档时遇到了问题。 我的项目布局如下:

项目文件夹

• 包
  • module1.py
  • 模块2.py
• 文档
  • 制作.bat
  • build
  • 来源
    • index.rst
    • package.rst
    • modules.rst
    • 配置文件

在 module1.py 和 module2.py 中有一些类(带有文档字符串)。我在 conf.py 中添加了以下行:

sys.path.insert(0, os.path.abspath('../../package'))

modules.rst 和 package.rst 都是通过调用生成的:

sphinx-apidoc -o doc/source package/

文件夹内。最后，我在 index.rst 文件中添加了“模块”，如下所示(不是整个 index.rst，但它是由 sphinx-quickstart 生成的):

Contents:

.. toctree::
   :maxdepth: 2

   modules

我有几个问题:

1) 当我从 doc/目录调用 sphinx-autodoc 时，文档没有生成。为了正确生成文档，我必须在 package.rst 中用 module1 替换 package.module1:

#before
.. automodule:: package.module1
    :members:
    :undoc-members:
    :show-inheritance:
#after
.. automodule:: module1
    :members:
    :undoc-members:
    :show-inheritance:

如何自动执行此操作？还是我的设置有问题？

2) 如果 module1.py 只包含一堆 def，则文档生成正确。但是，如果我只在其中放置一个类，则根本不会生成文档(请注意，即使在第二次运行 sphinx-apidoc 后，package.rst 文件仍保持不变)。如何显示类文档？

谢谢

Answer 1

好的，在查看了 sphinx 日志之后(我很遗憾没有将它们发布出来)我意识到了第一个问题的答案:如果你想使用 sphinx-apidoc 输出，你必须在 conf.py 中添加“包”的父级"包，不是包本身

sys.path.insert(0, os.path.abspath('../../')) #documentation is detected
sys.path.insert(0, os.path.abspath('../../package')) #documentation isn't detected

这样python就导入了PYTHONPATH中的文件夹，从而解决了“Package.module1”/“Package.module2”路径。 至于问题 #2，我意识到(再次，我的坏)sphinx 只为公共(public)成员生成文档，而我的类(class)只有 dunder 方法(如 __ init__)。如果您想记录这些方法(像我一样)，请务必在加载的模块下的 .rst 文件中添加:special-members:

.. automodule:: Package.module2
    :members:
    :undoc-members:
    :show-inheritance:
    :private-members: # if you want to document __x attributes
    :special-members: # if you want to document __xxx__ dunder methods