Sphinx, the best practices

Question

I just started to use Sphinx tool to generate a documentation for my code. But I'm a bit confused because it's not as easy as I expected. I create the Sphinx doc using:

sphinx-quickstart

and then I create my *.rst files into the "source" folder. Seems like I need to create a *.rst file for each module I want to create a document for. For test.py, I create test.rst. Inside test.rst, I have:

.. automodule:: test
    :members:
    :show-inheritance:

Then inside test.py, I have:

"""
.. module:: test
   :platform: Unix, Windows
   :synopsis: A useful module indeed.
"""

Then I generate the documentation using:

sphinx-build -b html source/ build/

Everything works as expected, but the problem is that it's not as easy as I expected. I guess that there must be an easier way to do it with skipping some of these steps. I wonder if there is any way to generate a documentation for all the modules inside a package instead of generating a *.rst file for each module.

Thanks.

Answer 1

There is no easier way. Sphinx is not an API doc generator like epydoc, but instead focuses on handwritten documentation. Consequently you need to write a lot of the documents by hand.

The advantage is, that you can also write documentation beyond API docs (e.g. tutorials, usage guides, even end user documentation), and that you can structure API documentation logically, beyond just a simple alphabetical listing of available objects. Such documentation is generally a lot easier to comprehend and a lot easier to use, if done correctly.

Take a look at the documentation of well-known projects (e.g. Werkzeug or Sphinx itself) to see some best practices.

Answer 2

One simple way to document your application quickly is to just write docstrings into classes and methods as per usual, and then complement them if required in the .rst files.

template.rst:

Templating
----------
Notes about templating would go here.

.. automodule:: myapp.lib.template
    :members:
    :undoc-members:

    .. py:attribute:: filepath

        Full path to template file. This attribute is added in runtime, so
        it has to be documented manually.

myapp/lib/template.py:

class Template(object):
    '''
    Class for rendering templates.

    Usage example::

        >>> t = Template('somefile')
        >>> document = t.render(variables={'ID': 1234})

    Rendered document is always returned as a unicode string.
    '''

    def render(self, **args):
        '''
        Render template. Keyword arguments are passed `as-is` to renderer.
        '''