linuxdoc 20260504

Sphinx-doc extensions & tools to extract documentation from C/C++ source file comments.

The LinuxDoc library contains Sphinx-doc extensions and command line tools to extract documentation from C/C++ source file comments. Even if this project started in context of the Linux-Kernel documentation, you can use these extensions in common Sphinx-doc projects.

linuxdoc is distributed under the terms of the AGPL-3.0-or-later license.

Install

Install LinuxDoc release from pypi using pip:

python -m pip install --user -U linuxdoc

Development

This project is managed by hatch, for development tasks you should install hatch:

pipx install hatch

The tools required for the developer environment are provided in the mise.toml configuration file (Mise En Place).

git clone https://github.com/return42/linuxdoc.git
cd linuxdoc
mise install

Format and lint your code before commit:

hatch run fix
hatch run check

To enter the development environment use shell dev:

hatch shell dev
# source "/share/linuxdoc/.venv/bin/activate"
# (.venv) $

To get a live build of documentation:

hatch run doc:man
hatch run doc:live

Hint

Don’t forget to build manual pages, otherwise you will see a message:

WARNING: download file not readable: dist/doc/man/user_function.2.gz [download.not_readable]

For project tasks & maintenance use:

hatch run prj --help

Build & Deploy

To force push online doc to the gh-pages branch:

hatch run doc:man
hatch run ./prj doc.gh-pages

Use hatch build command to build sdist an wheel:

hatch build -c

and hatch publish command to deploy on pypi (or test.pypi.org):

hatch publish -r https://test.pypi.org/legacy/ ./dist/linuxdoc-YYYYMMDD*
hatch publish ./dist/linuxdoc-YYYYMMDD*

Mise En Place

For the developer environment, mise en place is recommended:

$ curl https://mise.run | sh

# to install shell completions .. and mises's backends dependencies
$ mise use -g usage

To activate mise in the current bash session see mise activate --help. For a more streamlined setup, you can configure activation in your shell’s configuration file.

For the Bash shell, the following lines can be added to the ~/.bashrc file:

if [ -f "${HOME}/.local/bin/mise" ]; then
    eval "$("${HOME}/.local/bin/mise" activate bash --shims)"
fi

References

• Documentation: https://return42.github.io/linuxdoc

• Releases: https://pypi.org/project/linuxdoc/

• Code: https://github.com/return42/linuxdoc

• Issue tracker: https://github.com/return42/linuxdoc/issues

• License file: AGPLv3+

• mise en place: mise.toml

• Python

• Bash

• shellcheck