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

Question

我们不希望维护文档和源代码,而源代码目前正在迅速发展,但Sphinx似乎需要令人沮丧的设置和配置.(我们只需要一些基本的API文档.)是否有一个命令可以在python项目中运行,它只会迭代生成HTML文档的所有包,模块,类和函数？

sphinx-apidoc将内容splats到一个目录中,在修改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.