API¶

autodoc directive for Python APIs¶

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"

Overview

Connected objects

Problems

python_api_doc: Document Python API

Tools

sphinx: Sphinx

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 node "<size:12>Tool</size>\n**Sphinx**\n<size:10>sphinx</size>" as sphinx [[../tools/sphinx.html#sphinx]] #5d7ecb ' Connection definition sphinx_autodoc -[bold,#7dca5d]-> python_api_doc: solves sphinx_autodoc -[bold,#5d7ecb]-> sphinx: uses @enduml$

Problems

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

Tools

Tool: Sphinx sphinx

style: blue_border

used by: sphinx_autodoc, doxygen_sphinx, sphinx_needs_templates, sphinx_needs, breathe

Documentation generation framework for “Doc-As-Code” approach.

link: https://www.sphinx-doc.org

Demos

No needs passed the filters

Doxygen + breathe for C++ APIs in Sphinx¶

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

Overview

Connected objects

Problems

cpp_api_doc: Document C++ API in Sphinx

Tools

doxygen: Doxygen
sphinx: Sphinx
breathe: Breathe

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 node "<size:12>Tool</size>\n**Doxygen**\n<size:10>doxygen</size>" as doxygen [[../tools/documentation.html#doxygen]] #5d7ecb node "<size:12>Tool</size>\n**Sphinx**\n<size:10>sphinx</size>" as sphinx [[../tools/sphinx.html#sphinx]] #5d7ecb node "<size:12>Tool</size>\n**Breathe**\n<size:10>breathe</size>" as breathe [[../tools/sphinx.html#breathe]] #5d7ecb ' Connection definition doxygen_sphinx -[bold,#7dca5d]-> cpp_api_doc: solves doxygen_sphinx -[bold,#5d7ecb]-> doxygen: uses doxygen_sphinx -[bold,#5d7ecb]-> breathe: uses doxygen_sphinx -[bold,#5d7ecb]-> sphinx: uses breathe -[bold,#5d7ecb]-> doxygen: uses breathe -[bold,#5d7ecb]-> sphinx: uses @enduml$

Problems

I document my C++ APIs via Doxygen.

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

Tools

Tool: Doxygen doxygen

style: blue_border

used by: doxygen_sphinx, breathe

link: https://www.doxygen.nl/index.html

Tool: Sphinx sphinx

style: blue_border

used by: sphinx_autodoc, doxygen_sphinx, sphinx_needs_templates, sphinx_needs, breathe

Documentation generation framework for “Doc-As-Code” approach.

link: https://www.sphinx-doc.org

Tool: Breathe breathe

style: blue_border

uses: doxygen, sphinx

used by: doxygen_sphinx

Breathe provides a bridge between the Sphinx and Doxygen documentation systems.

link: https://breathe.readthedocs.io/en/latest/

Demos

Demo documents a C++ based API.

The API docs gets first generated by Doxygen. The sphinx extension Breathe reads in the Doxygen results and creates the needed data in this sphinx project.

Open demo

Analyse code on github

ID: needs_doxygen_breathe