如何使用Sphinx生成Python文档而不需要任何配置？

Question

我们不希望像维护源代码那样维护文档，因为源代码正在快速发展，但是 Sphinx 似乎需要大量的设置和配置，这让人感到沮丧。（我们只需要一些基本的 API 文档。）难道没有一个单独的命令可以在 python 项目内运行，然后迭代所有包、模块、类和函数并生成 HTML 文档吗？

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

谢谢！

- rosejn

Answer 1

sphinx-apidoc工具可以自动生成模块的桩代码，这可能是你想要的。

说明

• Make sure the autodoc module was enabled during Sphinx configuration.

  extensions = ['sphinx.ext.autodoc']
  

  within Sphinx's conf.py should do the trick.

• Make sure conf.py adjusts sys.path accordingly (see the comments at lines 16-19 in the file).

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

• Run sphinx-apidoc to generate skeletons.

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

• Rebuild the docs. If all goes well, you shouldn't get the following sort of warning:

  mymodule.rst:4: WARNING: autodoc can't import/find module 'mymodule'

• Your module RSTs should now be populated.

- AKX

---

我尝试过这个，但生成的HTML只有链接到空模块，里面没有任何函数或类。 - rosejn

我在答案中详细阐述了这个过程。希望对你有所帮助。 - AKX

我必须首先传递输出路径，才能运行sphinx-apidoc命令。 - Nevermore

我每次创建新文件时都需要运行sphinx-apidoc来创建框架吗？我习惯于使用Doxygen，它可以自动处理文档。 - c3cris