1

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

我安装了 Sphinx 1.1.3。我为文档做了第一步（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 的问题。我找到了这篇文章并尝试了解决方案，但我无法让它工作。

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

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

4

1 回答 1

0

range是一个python内置的，其行为在python3. python和版本/要求（相当旧）之间可能会有一些冲突sphinx。napoleonsphinx 1.1.3

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

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

于 2016-01-15T09:38:31.510 回答