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

时间:2013-02-26 13:54:09

标签: python python-sphinx documentation-generation

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

sphinx-apidoc splats stuff到一个目录中,在修改conf.py以使我们的包在sys.path中之后我们可以运行“make html”,但它只列出包和模块而不记录任何类或函数

谢谢!

1 个答案:

答案 0 :(得分:18)

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

说明

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

    extensions = ['sphinx.ext.autodoc']
    

    在Sphinx的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。