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. Forfile_3.h
, from the example above in Generated Documentation Files, this would besome_dir/another_dir/file_3.h
filename
The name of the file, without relative directory. Forfile_3.h
, from the example above in Generated Documentation Files, this would befile_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. Forfile_4.c
, from the example above in Generated Documentation Files, this would besome_dir/another_dir/file_4.c
filename
The name of the file, without relative directory. Forfile_4.c
, from the example above in Generated Documentation Files, this would befile_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.