Are there any real alternatives to reStructuredText for Python documentation? [closed]

Question

I'm starting an open source Python project shortly and I'm trying to decide in advance how to write my docstrings. The obvious answer would be using reStructuredText and Sphinx with autodoc, because I really like the idea of simply properly documenting my code in my docstrings then have Sphinx automatically construct an API doc for me.

The problem is the reStructuredText syntax it uses - I think it's completely unreadable before it's rendered. For instance:

:param path: The path of the file to wrap :type path: str :param field_storage: The :class:`FileStorage` instance to wrap :type field_storage: FileStorage :param temporary: Whether or not to delete the file when the File instance     is destructed :type temporary: bool 

You have to really slow down and take a minute to make any sense out of that syntactic jumble. I like much more the Google way (Google Python Style Guide), which counterpart to the above looks like this:

 Args:     path (str): The path of the file to wrap     field_storage (FileStorage): The FileStorage instance to wrap     temporary (bool): Whether or not to delete the file when the File         instance is destructed 

Way nicer! But of course, Sphinx will have none of that and renders all the text after Args: in one long line.

So to summarize - before I go and defile my code base with this reStructuredText syntax I would like to know if there are any real alternatives to using it and Sphinx, short of just writing my own API doc. For instance, is there an extension for Sphinx that handles Google Style Guide's docstring style?

Answer 1

I have created a Sphinx extension that parses both Google style and NumPy style docstrings, and converts them to standard reStructuredText.

To use it, simply install it:

$ pip install sphinxcontrib-napoleon  

And enable it in conf.py:

# conf.py  # Add autodoc and napoleon to the extensions list extensions = ['sphinx.ext.autodoc', 'sphinxcontrib.napoleon'] 

More documentation on napoleon here.

Answer 2

I don't think that there is something better than sphinx for documenting python projects at the moment.

To have a clearer docstring my favorite choice is using sphinx together with numpydoc. Based on your example this would look like:

def foo(path, field_storage, temporary):     """This is function foo      Parameters     ----------     path : str         The path of the file to wrap     field_storage : :class:`FileStorage`         The :class:`FileStorage` instance to wrap     temporary : bool         Whether or not to delete the file when the File instance         is destructed      Returns     -------     describe : type         Explanation     ...      Examples     --------     These are written in doctest format, and should illustrate how to     use the function.      >>> a=[1,2,3]     >>> print [x + 3 for x in a]     [4, 5, 6]     ...     """      pass 

(a full example is Here), HTML output will look like this

I think the structure of the rst-file is clearer and more readable. The guide gives some more information and conventions. The numpydoc extension works with autodoc as well.