Table of Contents¶

Overview¶

Sphinx is a tool that generates documentation from reStructuredText. Output formats include HTML, pdf, epub, manpage, and many others.

reStructuredText is a markup language primarily for python documentation.

Getting Started¶

In all current Ambition app templates, there is now a docs folder in the root of the project, this is the source for Sphinx documentation.

Common reStructuredText and Sphinx commands will be documented here:

• Python Docstrings
• Using Sphinx Autodoc
• Sphinx reStructuredText primer

Functions and Methods¶

For private methods and functions, please add just a sentence or two stating what it does. If the function or method has more than two parameters, you should probably document it like you would a public method, but use your good judgement.

For private, one line functions or methods, you only need a docstring if it’s not immediately obvious what you’re doing.

Please document public methods and attributes (methods and attributes that don’t start with an underscore) in the following format.

def power(num, x):
    """
    This function raises num to the power of x and returns the result

    :type num: int
    :param num: The number to raise

    :type x: int
    :param x: The power to raise the number to

    :rtype: int
    :returns: The result

    :raises: ValueError if x isn't an int

    .. code-block:: python

        >>> result = power(2, 3)
        >>> print result
        8

    """

The rendered output looks like this.

my_module.power(num, x)¶

This function raises num to the power of x and returns the result

Parameters:	num (int) – The number to raise x (int) – The power to raise the number to
Return type:	int
Returns:	The result
Raises:	ValueError if x isn’t an int

>>> result = power(2, 3)
>>> print result
8

Classes¶

Class documentation can be pretty simple, a sentence or two will usually do.

class Resource(object):
    """
    A base class for making API calls
    """
    def __init__(self, *args, **kwargs):
        pass

The rendered output looks like this.

my_module.Resource(*args, **kwargs)¶

A base class for making API calls

Functions¶

To document the function mymodule.power:

.. autofunction:: mymodule.power

Classes¶

To automatically document classes:

.. autoclass:: my_module.MyClass
    :members:
    :undoc-members:

• The :members: option will automatically generate all documented methods

• The :undoc-members: option will document all undocumented methods

• The :private-members: option will document private options (methods that

  start with one or two underscores. Ex: _private)

Modules¶

To document your module:

.. automodule:: mymodule

Setup¶

The file /docs/conf.py will have your sphinx configuration and will need the intersphinx_mappings directive configured. Ambition’s ambition-python-template and django-app-template both already have this set up. You will also need to make sure the library is in requirements/docs.txt.

intersphinx_mapping = {
    'python': ('http://python.readthedocs.org/en/v2.7.2/', None),
    'django': ('http://django.readthedocs.org/en/latest/', None),
    'celery': ('http://celery.readthedocs.org/en/latest/', None),
}

Usage¶

To use intersphinx in your documentation or docstrings, use the following format:

def my_function(model):
    """
    :type model: :class:`Models<django:django.db.models.Model>`
    :param model: The model you want work with
    """
    pass

The link will look like this Models.

Documentation Style¶

Please wrap text at 80 characters with a 120 character max.

Building the docs¶

When in the project directory:

$ pip install -r requirements.txt
$ cd docs && make html
$ open docs/_build/html/index.html

Release Checklist¶

Before a new release, please go through the following checklist:

• Bump version in version.py
• Git tag the version
• Add a release note in docs/release_notes/
• Add a link to the newest release note to docs/release_notes/index.rst

v0.1.1¶

• Added a python module my_module with example code to show how autodoc works.
• Edited links on the intro page and toc

v0.1¶

This is the initial release of ambition-docs-guide.