斯芬克斯，最佳实践

问题描述

我刚刚开始使用Sphinx工具为我的代码生成文档。但我有点困惑，因为这并不像我想象的那么容易。我使用：

创建Sphinx文档

sphinx-quickstart

然后我将我的*.rst文件创建到"源"文件夹中。似乎我需要为要为其创建文档的每个模块创建一个*.rst文件。对于test.py，我创建了test.rst。在test.rst中，我有：

.. automodule:: test
    :members:
    :show-inheritance:

然后在test.py中，我有：

"""
.. module:: test
   :platform: Unix, Windows
   :synopsis: A useful module indeed.
"""

然后我使用：

生成文档

sphinx-build -b html source/ build/

一切都按预期工作，但问题是它并不像我预期的那么容易。我想一定有一种更简单的方法来跳过其中的一些步骤。我想知道是否有任何方法可以为包中的所有模块生成文档，而不是为每个模块生成*.rst文件。

谢谢。

---

解决方案

没有更简单的方法。Sphinx不是像epydoc那样的API文档生成器，而是专注于手写文档。因此，您需要手写大量的文档。

其优势在于，您还可以编写API文档之外的文档(例如教程、使用指南，甚至终端用户文档)，并且您可以在简单的可用对象字母列表之外逻辑地组织API文档。如果操作正确，这样的文档通常更易于理解和使用。

查看知名项目(例如Werkzeug或Sphinx本身)的文档以了解一些最佳实践。