configuration.rst

Configuring

Configuration Variables

c_autodoc_roots

A list of directories which will be used to search for the files provided in the directives:Directives. The directories are relative to documentation source directory, often where conf.py is.

The list of directories will be searched in order so if duplicate named files exist the first one encountered in the directory list will be used.

Example:

c_autodoc_roots = ['my/source/dir', 'other/source/dir']

Then a directive of the form:

.. autocfunction:: some_file.c::some_function

would be searched first as my/source/dir/some_file.c then, if not found, it would be searched as other/source/dir/some_file.c. Again this relative to the top documentation source directory.

c_autodoc_compilation_database

Path to a compilation database. The compilation database is relative to the documentation source directory, often where conf.py is.

The compilation database will be used as the source of compile options for each file. If a file is listed more than once in the compilation database, only the first instance of the file will be used. Of importance is the directory entry for each file. The directory entry will be passed to libclang via the working-directory flag. The -working-directory allows for the includes and other path relative arguments to be handled consistently.

Note

Currently libclang only supports compilation databases named compile_commands.json.

c_autodoc_compilation_args

A list of arguments to pass to libclang. This can be used for setting common defines used only for documentation and/or avoiding areas of the code that have trouble parsing for documentation.

For example the following would result in libclang parsing the source files with the defines SPHINX_DOCS and SIMULATION:

c_autodoc_compilation_args = ["-DSPHINX_DOCS", "-DSIMULATION"]

c_autodoc_compilation_args are added for all files being processed. c_autodoc_compilation_args will be applied after any arguments provided by configuration:c_autodoc_compilation_database.

Events

c-autodoc-pre-process

There are times a project needs to perform some form of pre-processing of a source file prior to the build up of the auto-documentation. The c-autodoc-pre-process is a sphinx event that will be triggered prior to the parsing of the C file.

An example which replaces all instances of "the" with "this":

def pre_process(app, filename, contents, *args):
    file_body = contents[0]

    modified_contents = file_body.replace("the", "this")

    # replace the list to return back to the sphinx extension
    contents[:] = [modified_contents]

app.connect("c-autodoc-pre-process", pre_process)

autodoc-process-docstring

Since this is extending the autodoc functionality the autodoc events are available as well. Of particular interest may be the autodoc-process-docsting which will be emitted for every C construct.