Question

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

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

Could not import extension sphinxcontrib.napoleon (exception: cannot import name six)

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

Could not import extension sphinxcontrib.napoleon (exception: cannot import name range).

我不知道它是哪个包，我还没找到它，所以我卡住了。为了以防万一，我尝试了'sphinx.ext.napoleon'，但它找不到预期的扩展名。

我想尝试Sphinx 1.3和'sphinx.ext.napoleon'，它应与Sphinx一起发货。使用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文档字符串的完整文档（仍然自动生成？）

Answer 1

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

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

它不是您问题的直接解决方案/答案，但您也可以使用更新，更强大的python分发版，例如Anaconda（而不是陈旧的python） Ubuntu repos），它允许您使用最新的napoleon和sphinx版本而不会有太多麻烦。

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

1 个答案: