apidoc#

The sphinx-c-apidoc provides a way to generate documentation files for a C directory. It is meant to fulfill a similar role to the sphinx-apidoc command for python packages.

sphinx-c-apidoc#

usage: sphinx-c-apidoc [-h] [-o OUTPUT_PATH] [-f] [-t TEMPLATEDIR]
                       [--tocfile TOCFILE] [-d MAXDEPTH]
                       [--header-ext HEADER_EXT] [--source-ext SOURCE_EXT]
                       source_path
source_path#

Path to C source files to be documented

-h, --help#

show this help message and exit

-o <output_path>, --output-path <output_path>#

Directory to place the output files. If it does not exist, it is created

-f, --force#

Force overwriting of any existing generated files

-t <templatedir>, --templatedir <templatedir>#

Template directory for template files

--tocfile <tocfile>#

Filename for the root table of contents file (default: files)

-d <maxdepth>#

Maximum depth for the generated table of contents file(s). (default: 4)

--header-ext <header_ext>#

The extension(s) to use for header files (default: [“h”])

--source-ext <source_ext>#

The extension(s) to use for source files (default: [“c”])

Generated Documentation Files#

The generated documentation files will follow the same directory structure of the provide C source directory.

For example:

a_project
├── file_1.h
├── file_2.c
├── some_dir
│   ├── another_dir
│   │   ├── file_3.h
│   │   └── file_4.c

would result in:

doc_dir
├── files.rst
├── file_1_h.rst
├── file_2_c.rst
├── some_dir
│   ├── some_dir.rst
│   ├── another_dir
│   │   ├── another_dir.rst
│   │   ├── file_3_h.rst
│   │   └── file_4_c.rst

Where a_project was provided as the source_path and doc_dir was provided as the --output-path. files.rst is the root index or table of contents file. By default it only contains references to the other documentation files in the same directory and any index files in sub directories.

another_dir.rst is the index or table of contents file for the directory another_dir it will only contain references the files in that directory as well as any index files in subsequent sub directories.

Templates#

There are three jinja templates that are utilized for generating the documentation files. These can be overridden by passing a directory, via the --templatedir option, containing any of the templates to override.

header.rst.jinja2#

Controls the generation of files deemed to be header files, the --header-ext option.

Will be passed 2 arguments:

  • filepath The relative path to the file. For file_3.h, from the example above in Generated Documentation Files, this would be some_dir/another_dir/file_3.h

  • filename The name of the file, without relative directory. For file_3.h, from the example above in Generated Documentation Files, this would be file_3.h

source.rst.jinja2#

Controls the generation of files deemed to be source files, the --source-ext option.

Will be passed 2 arguments:

  • filepath The relative path to the file. For file_4.c, from the example above in Generated Documentation Files, this would be some_dir/another_dir/file_4.c

  • filename The name of the file, without relative directory. For file_4.c, from the example above in Generated Documentation Files, this would be file_4.c

toc.rst.jinja2#

Controls the generation of index or table of contents files.

Will be passed 3 arguments:

  • title The name of the index file without extension.

  • maxdepth The -d option.

  • doc_names The list of documentation files in the directory as well as those in subdirectories.