The very idea of writing documentation sounds tedious to some, this guide aims to remove mental blocks by synthesizing some of the most common tasks for writing documentation.
By the end of the guide you will know:
sphinx.ext.intersphinx
Sphinx ships with the sphinx.ext.autodoc which generates the classic API Reference section of many known open source libraries such as Flask, requests and boto3.
sphinx.ext.autodoc
Example Code
def make_user(email, password, admin=False, **kwargs): """creates structured user data for storage :param email: string :param password: in plain-text :param admin: bool - indicates user has all priviledges :param kwargs: extra data :returns: a :py:class:`dict` with user data """ data = locals() data.update(data.pop('kwargs')) return data
Reference function in a rst document
.. autofunction:: sphinx_bulma_theme.example.make_user
Rendered HTML:
sphinx_bulma_theme.example.
make_user
creates structured user data for storage
a dict with user data
dict