Sphinx 不处理 python 类

Question

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

project_folder

包
- module1.py
- module2.py
文档
- make.bat
- 建设
- 来源
  - index.rst
  - package.rst
  - modules.rst
  - conf.py

在 module1.py 和 module2.py 中有一些 classes（带有文档字符串）。我在 conf.py 中添加了以下行：

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

modules.rst 和 package.rst 都已通过调用生成：

sphinx-apidoc -o doc/source package/

文件夹内。最后，我在 index.rst 文件中添加了 "modules" 如下所示（不是整个 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只包含一堆defs，说明文档生成正确。但是，如果我只在其中放置一个 class，则根本不会生成文档（请注意，即使在运行第二次生成 sphinx-apidoc 之后，package.rst 文件仍保持不变）。如何显示 class 文档？

谢谢

Answer 1

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

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

Sphinx 不处理 python 类

Sphinx doesn't process python classes

python

python-sphinx

autodoc