我正在编写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制作好的文档(仍然自动生成)?