Unable to create documentation with Sphinx and Google docstrings

Question

I am writing a Python API and I have documented every class and function in the sources using Google docstring convention, which I find way more readable than the Sphinx convention. I want to use Sphinx to build the documentation for my API. There is an extension called Napoleon that supports Numpydoc and Google docstrings, so I tried to use it and I encountered several problems. I am using Python 2.7.3 on Ubuntu 12.04.

I have Sphinx 1.1.3 installed. I did the first steps for the doc (sphinx-quickstart, with the autodoc enabled and a make file). I read that before Sphinx 1.3, I had to add sphinxcontrib.napoleon as an extension in the conf.py of my doc. I did that, and got the error that the extension napoleon could not be found. I downloaded it, installed it, and then I had the error that a certain package could not be found :

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

This was the name of a package in the requirement file, so I installed it. I had the same error with another package, I installed it also. Now I have the same error but with "range":

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

I don´t know which package it is, I haven´t found it anywhere, so I´m stuck. I tried ´sphinx.ext.napoleon´ just in case but it couldn't find the extension, which was expected.

I wanted to try then with Sphinx 1.3 and ´sphinx.ext.napoleon´ that should be shipped with Sphinx. When installing with apt-get, I only get version 1.1.3, even after an update. So I tried downloading directly and installing Sphinx 1.3, but got the following errors :

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)

It seems to be a problem with setuptools. I found this post and tried the solution but I cannot get it to work.

I know I could change all my docstring but that would take time and be less readable. I can try something else than Sphinx but Sphinx is the most common documentation tool for Python, that´s why I tried to stick with it.

How can I get a good documentation (still automatically) made from the Google docstring in my sources ?

Answer 1

range is a python built-in, whose behavior changed in python3. There could be some fight between python, sphinx and napoleon versions/requirements (sphinx 1.1.3 is rather old).

With concern to your last question (automatic documentation), you should look into the autodoc extension. If you want even more automation, look into the apidoc script, which is included in sphinx > 1.1.

It is not a direct solution/answer to your problem, but you could also use a more up-to-date and robust python distribution such as Anaconda (rather than the stale python in the Ubuntu repos), which would allow you to use the most recent napoleon and sphinx versions without much hassle.