sphinx.md

Sphinx

Check installation:

$ python -c 'import sphinx; print sphinx.__version__'

Follow the installation instructions, install by:

$ easy_install -U Sphinx

In the doc/ directory:

The index.rst is the master ReST for your project.

The conf.py is the file that controls the basics of how sphinx runs when you run a build. Here you can do this like:

• Change the version/release number by setting the version and release variables.
• Set the project name and author name.
• Set the default style to sphinx or default. Default is what the standard python docs use.

Read more here

sphinx.ext.autodoc – Include documentation from docstrings

For module data members and class attributes, documentation can either be put into a comment with special formatting (using a #: to start the comment instead of just #), or in a docstring after the definition. Comments need to be either on a line of their own before the definition, or immediately after the assignment on the same line. The latter form is restricted to one line only.

This means that in the following class definition, all attributes can be autodocumented:

class Foo:
    """Docstring for class Foo."""

    #: Doc comment for class attribute Foo.bar.
    #: It can have multiple lines.
    bar = 1

    flox = 1.5   #: Doc comment for Foo.flox. One line only.

    baz = 2
    """Docstring for class attribute Foo.baz."""

    def __init__(self):
        #: Doc comment for instance attribute qux.
        self.qux = 3

        self.spam = 4
        """Docstring for instance attribute spam."""

Read more here

sphinx.ext.todo – Support for todo items

Sphinx can process todo items specified with the special todo directive. It can be included in the docstring:

def post(self):
    """
    Adds a :class:`Persona` resource in Persona resource list.

    :returns: A newly created Persona resource with http 201 response code.

    .. todo::

       Validate all post fields 

    """

Read more here

Sphinx Domains

One can reference classes, functions and the like. For example:

.. py:function:: send_message(sender, recipient, message_body, [priority=1])

   Send a message to a recipient

   :param str sender: The person sending the message
   :param str recipient: The recipient of the message
   :param str message_body: The body of the message
   :param priority: The priority of the message, can be a number 1-5
   :type priority: integer or None
   :return: the message id
   :rtype: int
   :raises ValueError: if the message_body exceeds 160 characters
   :raises TypeError: if the message_body is not a basestring

Read more here

Cheat Sheet