无法使用Sphinx和Google docstrings创建文档

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

我已经安装了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)

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

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

我不知道它是哪个包，我发现haven't在任何地方，所以I'm卡住。为了防万一，我尝试了'phinx.ext.napoleon'，但无法找到预期的扩展名。

我想尝试一下与狮身人面像一起发货的Sphinx 1.3和sphinx.ext.napoleon。使用apt-get进行安装时，即使在更新后，我也只能获得版本1.1.3。所以，我想直接下载过和安装狮身人面像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文档字符串中获得一份很好的文档（仍然是自动的）？

来源

2016-01-15 Enaid

range是python内置的，其行为更改为python3。 python,sphinx和napoleon版本/要求（sphinx 1.1.3比较旧）之间可能会有一些争执。

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

这不是您的问题的直接解决方案/答案，但您也可以使用更新，更稳健的python分配，例如Anaconda（而不是Ubuntu回购协议中的陈旧python），这将允许您可以毫不费力地使用最新的napoleon和sphinx版本。

来源

2016-01-15 09:38:31 charlie80

我已经在使用autodoc扩展和apidoc脚本，它们工作正常，但不会将Google文档转换为rps。我会研究Anaconda。 – Enaid

当然，那是因为你需要让拿破仑工作，他是解释Google风格文档的人。 – charlie80

是的，我知道，这是我的问题的核心。应该有办法让Napoleon在没有安装全新的python发行版的情况下工作，不是吗？ – Enaid

无法使用Sphinx和Google docstrings创建文档

回答

相关问题