15

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.

mzjn
  • 48,958
  • 13
  • 128
  • 248
pocoa
  • 4,197
  • 9
  • 37
  • 45

3 Answers3

12

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.

  • 2
    @pocoa: It is possible to automate generation of .rst files. See my answer to this question: http://stackoverflow.com/questions/5301218. – mzjn May 24 '11 at 14:55
  • @mzjn Thanks, but I couldn't find any documentation about this sphinx-apidoc script. – pocoa May 24 '11 at 15:02
  • 1
    @pocoa: Sphinx 1.1 has not been released, so it's not very surprising that there is little documentation. The module that does the real work is here: https://bitbucket.org/birkenfeld/sphinx/src/47a94f723e80/sphinx/apidoc.py. – mzjn May 24 '11 at 15:10
  • Sphinx 1.1 has been released now, so sphinx-apidoc is now available. – Joshua Olson Feb 06 '12 at 23:14
10

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.
        '''
tuomur
  • 6,888
  • 34
  • 37
3

You can use sphinx-apidoc to create the rst files for you.

sphinx-apidoc -o outputdir pythondir

Example run output:

% sphinx-apidoc -o source/ ../
File source/module1.rst already exists, skipping.
File source/module2.rst already exists, skipping.
Creating file source/module3.rst.

rst docs updated in source/.

sphinx-apidoc won't modify existing files, you can force overwrite with the -f flag.

spazm
  • 4,399
  • 31
  • 30
  • Might be my own ignorance but the default output creates one big html page with (the doc strings of) all your modules and classes and methods just one after the other. I find this pretty useless. – Raik Aug 03 '17 at 19:18
  • @Raik see the ``sphinx-apidoc`` command line help which describes the ``-e`` or ``--separate`` option to "Put documentation for each module on its own page". – Peter Cock Sep 14 '17 at 10:35
  • @peterjc Haven't seen this one but it looks promising, thanks! I ended up using `.. autosummary::` at the module-level but with a custom template that first lists all class methods and then uses autosummary to give the detailed method and field doc strings. – Raik Sep 15 '17 at 11:46
  • Thanks @Raik - using ``sphinx-apidoc`` does seem quite limiting, and does not currently support custom templates - but keep an eye on https://github.com/sphinx-doc/sphinx/issues/3545 – Peter Cock Sep 18 '17 at 14:19