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

问题描述 投票:0回答:1

我正在编写Python API,并且已经使用Google docstring约定记录了源代码中的每个类和函数,与Sphinx约定相比,我发现它更具可读性。我想使用Sphinx为我的API构建文档。有一个名为Napoleon的扩展程序,它支持NumpydocGoogle 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制作好的文档(仍然自动生成)?

python python-sphinx setuptools docstring sphinx-napoleon
1个回答
0
投票

range是内置的python,其行为在python3中已更改。 pythonsphinxnapoleon版本/要求之间可能会发生争执(sphinx 1.1.3较旧)。

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

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

© www.soinside.com 2019 - 2024. All rights reserved.