无法使用 Sphinx 和 Google 文档字符串创建文档
Unable to create documentation with Sphinx and Google docstrings
我正在写一个 Python API 并且我已经使用 Google docstring[=42= 记录了源代码中的每个 class 和函数] 约定，我发现它比 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 的错误。我下载了，安装了，然后出现找不到某个包的错误:
Could not import extension sphinxcontrib.napoleon (exception: cannot import name six)
这是需求文件中的包名，所以我安装了它。我对另一个包有同样的错误，我也安装了它。现在我有同样的错误但是 "range":
Could not import extension sphinxcontrib.napoleon (exception: cannot import name range).
我不知道它是哪个包，我在任何地方都找不到它，所以我卡住了。我尝试了“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)
这似乎是设置工具的问题。我找到了这个 post 并尝试了解决方案，但我无法让它工作。
我知道我可以更改我的所有文档字符串，但这需要时间并且可读性较差。除了 Sphinx，我还可以尝试其他工具，但 Sphinx 是 Python 最常用的文档工具，这就是我尝试坚持使用它的原因。
如何从我的资源中的 Google docstring 获得一份好的文档（仍然是自动的）？
range 是 python built-in，其行为在 python3 中发生了变化。 python、sphinx 和 napoleon versions/requirements 之间可能会有一些争斗（sphinx 1.1.3 相当老）。
关于您的最后一个问题（自动文档），您应该查看 autodoc extension. If you want even more automation, look into the apidoc 脚本，它包含在 sphinx > 1.1.
中
这不是直接 solution/answer 您的问题，但您也可以使用更 up-to-date 和更强大的 python 分布，例如 Anaconda （而不是Ubuntu 存储库中的陈旧 python），这将使您可以轻松使用最新的 napoleon 和 sphinx 版本。
我正在写一个 Python API 并且我已经使用 Google docstring[=42= 记录了源代码中的每个 class 和函数] 约定，我发现它比 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 的错误。我下载了，安装了，然后出现找不到某个包的错误:
Could not import extension sphinxcontrib.napoleon (exception: cannot import name six)
这是需求文件中的包名，所以我安装了它。我对另一个包有同样的错误，我也安装了它。现在我有同样的错误但是 "range":
Could not import extension sphinxcontrib.napoleon (exception: cannot import name range).
我不知道它是哪个包，我在任何地方都找不到它，所以我卡住了。我尝试了“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)
这似乎是设置工具的问题。我找到了这个 post 并尝试了解决方案，但我无法让它工作。
我知道我可以更改我的所有文档字符串，但这需要时间并且可读性较差。除了 Sphinx，我还可以尝试其他工具，但 Sphinx 是 Python 最常用的文档工具，这就是我尝试坚持使用它的原因。
如何从我的资源中的 Google docstring 获得一份好的文档（仍然是自动的）？
range 是 python built-in，其行为在 python3 中发生了变化。 python、sphinx 和 napoleon versions/requirements 之间可能会有一些争斗（sphinx 1.1.3 相当老）。
关于您的最后一个问题（自动文档），您应该查看 autodoc extension. If you want even more automation, look into the apidoc 脚本，它包含在 sphinx > 1.1.
这不是直接 solution/answer 您的问题，但您也可以使用更 up-to-date 和更强大的 python 分布，例如 Anaconda （而不是Ubuntu 存储库中的陈旧 python），这将使您可以轻松使用最新的 napoleon 和 sphinx 版本。