API¶

Document Python API¶

How can I document the API of my Python based application?

Overview

Solutions

sphinx_autodoc: autodoc directive for Python APIs

Flowchart

$@startuml ' Nodes definition node "<size:12>Problem</size>\n**Document Python**\n**API**\n<size:10>python_api_doc</size>" as python_api_doc [[../problems/api.html#python_api_doc]] #cb5d7e node "<size:12>Solution</size>\n**autodoc**\n**directive for**\n**Python APIs**\n<size:10>sphinx_autodoc</size>" as sphinx_autodoc [[../solutions/api.html#sphinx_autodoc]] #7dca5d ' Connection definition sphinx_autodoc -[bold,#7dca5d]-> python_api_doc: solves @enduml$

Solutions

Use the sphinx feature autodoc to automatically document an API by using the docstrings of related python based objects (modules, classes, functions, …).

.. autoclass my_app.my_module.my_class
   :members:  # Add all public mebmers with a docstring
   :undoc-members:  # Add members without a docstring
   :private-members  # Add also private members like "_my_secret"

Document C++ API in Sphinx¶

I document my C++ APIs via Doxygen.

Is there a way to do the API documentation of C++ inside Sphinx?

Overview

Solutions

doxygen_sphinx: Doxygen + breathe for C++ APIs in Sphinx

Flowchart

$@startuml ' Nodes definition node "<size:12>Problem</size>\n**Document C++**\n**API in Sphinx**\n<size:10>cpp_api_doc</size>" as cpp_api_doc [[../problems/api.html#cpp_api_doc]] #cb5d7e node "<size:12>Solution</size>\n**Doxygen +**\n**breathe for C++**\n**APIs in Sphinx**\n<size:10>doxygen_sphinx</size>" as doxygen_sphinx [[../solutions/api.html#doxygen_sphinx]] #7dca5d ' Connection definition doxygen_sphinx -[bold,#7dca5d]-> cpp_api_doc: solves @enduml$

Solutions

Doxygen must be installed on the system! And Breathe must be installed as Python package on the used virtual environment.

# conf.py

# Executes doxygen.
# This makes sure that the extension "breathe" has access to the latest API information.

extensions = ['breathe']

if shutil.which("doxygen"):
    breathe_projects = {
        "doxygen_example": "_build/doxygen/xml"
        }
    breathe_default_project = "doxygen_example"

    if not os.environ.get("SKIP_DOXYGEN", None) == "True":
        for prjname, prjdir in breathe_projects.items():
            print("Generating doxygen files for {}...".format(prjname))
            os.makedirs(prjdir, exist_ok=True)
            cmd = "cd code && doxygen {}.dox".format(prjname)
            subprocess.call(cmd, shell=True)
    else:
        for prjname, prjdir in breathe_projects.items():
            assert os.path.exists(prjdir) == True, \
                "Regenerate doxygen XML for {}".format(prjname)

.. index.rst

.. doxygenfile:: doxygen_example.hpp
   :project: doxygen_example