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

Answer 1

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.