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

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 listextensions = ['sphinx.ext.autodoc', 'sphinxcontrib.napoleon']

More documentation on napoleon here.

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.

I use epydoc and not sphinx, so this answer may not apply.

The reStructuredText syntax you describe for documenting methods and functions is not the only possible one. By far, I prefer describing parameters using a consolidated definition list, which is very similar to the Google way:

:Parameters:  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

I would try out if sphix supports it. If it doesn't you may also consider using epydoc just for that (although it is not that actively maintaned right now).