python - 对于 Python 文档，reStructuredText 有什么真正的替代品吗？

Question

已结束。此问题不符合 Stack Overflow guidelines .它目前不接受答案。

---

我们不允许提出有关书籍、工具、软件库等方面的建议的问题。您可以编辑问题，以便用事实和引用来回答它。

关闭 4 年前。

Improve this question

我很快就开始了一个开源 Python 项目，我正在尝试提前决定如何编写我的文档字符串。显而易见的答案是使用带有 autodoc 的 reStructuredText 和 Sphinx，因为我真的喜欢简单地在我的文档字符串中正确记录我的代码然后让 Sphinx 自动构建一个 API 文档我。

问题在于它使用的 reStructuredText 语法——我认为它在渲染之前完全不可读。例如:

:param path: The path of the file to wrap
:type path: str
:param field_storage: The :class:`FileStorage` instance to wrap
:type field_storage: FileStorage
:param temporary: Whether or not to delete the file when the File instance
    is destructed
:type temporary: bool

你必须真的放慢速度，花一分钟时间从语法困惑中找出任何意义。我更喜欢 Google 的方式(Google Python Style Guide)，上面的对应方式如下所示:

Args:    path (str): The path of the file to wrap    field_storage (FileStorage): The FileStorage instance to wrap    temporary (bool): Whether or not to delete the file when the File        instance is destructed

方式更好!但当然，Sphinx 将没有这些，而是​​将 Args: 之后的所有文本呈现在一行中。

总结一下——在我去使用这种 reStructuredText 语法污染我的代码库之前，我想知道是否有任何真正的替代方法可以使用它和 Sphinx，而不仅仅是编写我自己的 API 文档。例如，是否有处理 Google Style Guide 的文档字符串样式的 Sphinx 扩展？

Answer 1

我创建了一个 Sphinx extension解析 Google 样式和 NumPy 样式的文档字符串，并将它们转换为标准的 reStructuredText。

要使用它，只需安装它:

$ pip install sphinxcontrib-napoleon 

并在 conf.py 中启用它:

# conf.py

# Add autodoc and napoleon to the extensions list
extensions = ['sphinx.ext.autodoc', 'sphinxcontrib.napoleon']

关于拿破仑的更多文档 here .