Sphinx apidoc usage

Build

# generate apidocs (before sphinx's `make html`)
sphinx-apidoc \
  --separate \
  -d 3 \
  -o ./_api \
  project/path

# launch pdb if sphinx fails to build
sphinx-build -P

Code

preparing your code

If you want a clean representation of your codebase, make sure that you follow python's conventions for public/private classes, functions, methods, and modules.

## private functions, methods, classes, python-modules
## will not be documented by default
##
def _private_func():
	pass

class _PrivateClass(object):
	pass

If you import modules into your __init__.py, modules included in the __all__ variable will be documented in sphinx as members.

from .mymodule import *
__all__ = [
	'function_from_mymodule',
	'function_from_mymodule2',
]

If you are trying to hide a module from sphinx make it a private module by adding 2x underscores to it's name. (even if there are public callables within it, they will not appear in sphinx).

#### /path/to/package/__mymodule.py

def public_function():
	pass

documenting your code

There are a handful of different ways of documenting your code, I've been using the napoleon extension, whose syntax I have covered in greater detail below.

Generally speaking though, your doctags will look like this:

def some_func():
    """
    A description of your function

    Args:
        car_brand (str):  ``(ex: 'Honda', 'Toyota', ...)``
            The Manufacturer of your car

        car_type (str): ``(ex: 'Sedan', 'SUV', ...)``
            The type of car you have

        colour Optional([str]): ``(ex: 'red', 'green', 'plaid', ...)``
            The colour of your car.

        available_materials (obj):
            :type:  :py:obj:`path.to.pkg.MyObject`
            An object that stores the available materials.

    Attributes:
        fuel_remaining (float):  The fuel left in the tank
        durability(float):       The remaining durability of the car


    .. versionadded:: 3.6
    .. versionchanged:: 3.6

    Returns:
        .. code-block:: python

            A dictionary with your car's info.
    """
    pass