Sphinx apidoc usage
From wikinotes
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(): passdocumenting 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