无法使用 Sphinx 和 Google 文档字符串创建文档答案

【问题标题】：Unable to create documentation with Sphinx and Google docstrings无法使用 Sphinx 和 Google 文档字符串创建文档
【发布时间】：2016-01-15 08:52:11
【问题描述】：

我正在编写一个 Python API，并且我使用 Google docstring 约定记录了源代码中的每个类和函数，我发现它比 Sphinx 约定更具可读性。我想使用 Sphinx 为我的 API 构建文档。有一个名为 Napoleon 的扩展程序支持 Numpydoc 和 Google docstrings，所以我尝试使用它，但遇到了几个问题。我在 Ubuntu 12.04 上使用 Python 2.7.3。

我安装了 Sphinx 1.1.3。我为文档做了第一步（sphinx-quickstart，启用了autodoc 和一个make 文件）。我在 Sphinx 1.3 之前读到过，我必须在我的文档的 conf.py 中添加 sphinxcontrib.napoleon 作为扩展名。我这样做了，并得到了无法找到扩展名napoleon 的错误。我下载了，安装了，然后出现找不到某个包的错误：

无法导入扩展 sphinxcontrib.napoleon（例外：无法导入名称六）

这是需求文件中一个包的名称，所以我安装了它。我对另一个软件包有同样的错误，我也安装了它。现在我有同样的错误，但“范围”：

无法导入扩展 sphinxcontrib.napoleon（例外：无法导入名称范围）。

我不知道它是哪个包裹，我在任何地方都没有找到它，所以我被卡住了。我尝试了“sphinx.ext.napoleon”以防万一，但它找不到扩展名，这是预期的。

我想尝试使用 Sphinx 1.3 和应该与 Sphinx 一起提供的“sphinx.ext.napoleon”。使用 apt-get 安装时，即使在更新后，我也只能获得 1.1.3 版本。所以我尝试直接下载并安装Sphinx 1.3，但出现以下错误：

Processing ./Sphinx-1.3.4.tar.gz
    Complete output from command python setup.py egg_info:
    /usr/lib/python2.7/distutils/dist.py:267: UserWarning: Unknown distribution option: 'entry_points'
      warnings.warn(msg)
    /usr/lib/python2.7/distutils/dist.py:267: UserWarning: Unknown distribution option: 'extras_require'
      warnings.warn(msg)
    /usr/lib/python2.7/distutils/dist.py:267: UserWarning: Unknown distribution option: 'include_package_data'
      warnings.warn(msg)
    /usr/lib/python2.7/distutils/dist.py:267: UserWarning: Unknown distribution option: 'zip_safe'
      warnings.warn(msg)
    /usr/lib/python2.7/distutils/dist.py:267: UserWarning: Unknown distribution option: 'install_requires'
      warnings.warn(msg)

似乎是 setuptools 的问题。我找到了这个post 并尝试了解决方案，但我无法让它工作。

我知道我可以更改所有文档字符串，但这需要时间并且可读性较差。我可以尝试除 Sphinx 之外的其他东西，但 Sphinx 是 Python 最常见的文档工具，这就是我尝试坚持使用它的原因。

我怎样才能从我的来源中的 Google 文档字符串中获得一个好的文档（仍然是自动的）？

【问题讨论】：

标签： python python-sphinx setuptools docstring sphinx-napoleon

【解决方案1】：

range 是一个 python 内置函数，它的行为在 python3 中发生了变化。 python、sphinx 和 napoleon 版本/要求之间可能存在一些冲突（sphinx 1.1.3 相当旧）。

关于您的最后一个问题（自动文档），您应该查看 autodoc 扩展名。如果您想要更多自动化，请查看apidoc 脚本，该脚本包含在sphinx > 1.1 中。

这不是您问题的直接解决方案/答案，但您也可以使用更新和强大的 python 发行版，例如 Anaconda（而不是 Ubuntu 存储库中的陈旧 python），这将允许您轻松使用最新的 napoleon 和 sphinx 版本。

【讨论】：

我已经在使用 autodoc 扩展和 apidoc 脚本，它们工作正常，但不要将 Google 文档字符串转换为 rps。我会调查 Anaconda。
当然，那是因为你需要让napoleon 工作，他是负责解释谷歌风格的文档字符串的人
是的，我知道，这就是我的问题的核心。应该有一种方法可以让拿破仑工作而无需安装全新的 python 发行版，不是吗？
在您原来的问题中，automation 是作为一个单独的问题出现的，这就是我回答的原因。下次，不要在您的问题中添加不相关的细节。
不，自动化不是一个单独的问题，因为如果我不希望它是自动的，我就不会在源代码中已经有某种格式的文档字符串，我可以在另一种形式。另外，我说我已经在使用 autodoc。我还指定了自动化，以防有人想提出一种与 Sphinx 完全不同的方式，那么它就必须有自动文档可用。我清楚地说我的问题是，现在仍然是谷歌文档字符串。不过，感谢您提供帮助。