python - 如何使用零配置的 Sphinx 生成 Python 文档？

Question

我们不想同时维护文档和源代码，目前它们正在迅速发展，但 Sphinx 似乎需要大量的设置和配置。（我们只需要一些基本的 API 文档。）难道没有一个命令可以在 python 项目中运行，它将遍历所有包、模块、类和函数，生成 HTML 文档？

sphinx-apidoc 将东西放到一个目录中，在修改 conf.py 以将我们的包放在 sys.path 中之后，我们可以运行“make html”，但它只列出包和模块，而没有记录任何类或函数。

谢谢！

Answer 1

该sphinx-apidoc工具将为您的模块自动生成存根，这可能是您想要的。

指示

• 确保autodoc在 Sphinx 配置期间启用了该模块。

  extensions = ['sphinx.ext.autodoc']
  

  在狮身人面像内conf.py应该做的伎俩。

• 确保进行conf.py相应调整sys.path（参见文件中第 16-19 行的注释）。

  sys.path.insert(0, os.path.abspath('/my/source/lives/here'))
  

• 运行sphinx-apidoc以生成骨架。

  sphinx-apidoc -o /my/docs/live/here /my/source/lives/here
  

• 重建文档。如果一切顺利，您应该不会收到以下警告：

  mymodule.rst:4：警告：autodoc 无法导入/查找模块“mymodule”

• 现在应该填充您的模块 RST。