2

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 ?

bad_coder
  • 11,289
  • 20
  • 44
  • 72
Enaid
  • 305
  • 1
  • 18

1 Answers1

0

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.

charlie80
  • 806
  • 1
  • 7
  • 17
  • I am already using the autodoc extension and the apidoc scripts, which work fine, but don´t convert Google docstrings to rps. I will look into Anaconda. – Enaid Jan 15 '16 at 10:21
  • sure, that's because you need to get `napoleon` working, he's the one who does the job of interpreting the Google-style docstrings – charlie80 Jan 15 '16 at 13:19
  • Yes I know, and that´s the core of my problem. There should be a way to make napoleon work without installing a whole new python distribution, no ? – Enaid Jan 15 '16 at 13:37
  • In your original question, *automation* appeared as a separate issue, that's the reason for my answer. Next time, don't add irrelevant details to your question. – charlie80 Jan 15 '16 at 13:56
  • No, automation is not a separate issue, because if I did not want it to be automatic, I would not have docstrings in a certain format already in the sources, and I could just write new documentation in another form. Plus I said I was already using autodoc. I also specified automation in case someone wanted to propose a completely different way than with Sphinx, it would have then to have automatic doc available. I clearly said my problem was, and still is, with Google docstring. Thank you for trying to help though. – Enaid Jan 15 '16 at 14:09
  • ok ok, I get your point, sorry for being rude. Anyway, about the python distribution, switching to Anaconda is a matter of minutes, so I think it's worth a shot. – charlie80 Jan 15 '16 at 14:16
  • I tried Anaconda, and it seems to not have any problem with the napoleon extension, cheers. However there are some packages that I need installed for my code (rospkg, pocketsphinx) and anaconda doesn´t seem to want to install them (no result with ´conda search´, nor pip). I am left with building my doc with Anaconda (with import statements commented) and returning to system python for developing, it works, but that´s not an ideal solution. – Enaid Jan 15 '16 at 15:01
  • even within Anaconda, you can `pip install` anything you want from `pypi`, since `conda` and `pip` can work together. What problem are you experiencing with `pip install rospkg` and `pip search pocketsphinx`? – charlie80 Jan 15 '16 at 15:05
  • Although pocketsphinx is on pypi, I get this weirdly unexplanatory error after `pip install pocketsphinx` : `Could not find a version that satisfies the requirement pocketsphinx (from versions: ) No matching distribution found for pockets phinx` When I do `pip search pocketsphinx`, I get an `SSLError: [SSL: CERTIFICATE_VERIFY_FAILED]`. I don´t really know how to get around those SSL certification errors, I´m at work and can´t mess around too much. (Same happens with `rospkg`) – Enaid Jan 15 '16 at 15:24
  • try the following: `conda update openssl cryptography` and then `conda update certifi` ([source](https://github.com/ContinuumIO/anaconda-issues/issues/494#issuecomment-155097614)) – charlie80 Jan 15 '16 at 15:27
  • I had to install certify, then I updated in order but same results. And even with ssl_verify set to False, I still get the exact same errors... I will search and try to fix this and maybe open a new question for it since it´s getting pretty far from the original question. Thanks for the help. – Enaid Jan 15 '16 at 15:47