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

Question

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

我已经安装了Sphinx 1.1.3。我为doc做了第一步（sphinx-quickstart，已启用autodoc和一个make文件）。我读到在Sphinx 1.3之前，我不得不在文档的sphinxcontrib.napoleon中添加conf.py作为扩展。我这样做了，并得到一个错误，即找不到扩展名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 docstring制作好的文档（仍然自动生成）？

Answer 1

range是内置的python，其行为在python3中已更改。 python，sphinx和napoleon版本/要求之间可能会发生争执（sphinx 1.1.3较旧）。

关于您的最后一个问题（自动文档），您应该研究autodoc扩展名。如果要进一步自动化，请查看autodoc中包含的apidoc脚本。

这不是解决问题的直接方法/答案，但是您也可以使用更新和更健壮的sphinx > 1.1发行版，例如python（而不是Ubuntu仓库中的陈旧python），可以让您轻松使用最新的Anaconda和napoleon版本。