Linuxdoc

20240924 verified Fri May 01 auth: no python

Sphinx-doc extensions and tools to extract documentation from C/C++ source file comments, including kernel-doc support. Current version 20240924. Released as needed, no fixed cadence.

pip install linuxdoc

Common errors

error ModuleNotFoundError: No module named 'linuxdoc' ↓

cause Package not installed or wrong Python environment.

fix

Run pip install linuxdoc in your active environment.

error WARNING: unknown directive type 'kernel-doc' ↓

cause KernelDocDirective not registered in Sphinx conf.py.

fix

Add app.add_directive('kernel-doc', KernelDocDirective) in setup function after importing.

error Exception occurred: AttributeError: module 'linuxdoc' has no attribute 'KernelDocDirective' ↓

cause Incorrect import; KernelDocDirective is in submodule.

fix

Use from linuxdoc.kernel_doc import KernelDocDirective.

Warnings

gotcha As of version 20240924, the import path for KernelDocDirective is `linuxdoc.kernel_doc.KernelDocDirective`; importing from top-level `linuxdoc.KernelDocDirective` fails. ↓

fix Use `from linuxdoc.kernel_doc import KernelDocDirective`.

gotcha The extension is meant for C/C++ kernel-doc comments; it may not work with other comment styles. ↓

fix Ensure source files use kernel-doc style comments (e.g., /** ... */).

gotcha Linuxdoc requires Sphinx; incompatible Sphinx versions may cause failures. Check compatibility with your Sphinx version. ↓

fix Use Sphinx version that matches linuxdoc's requirements (see setup.py/requirements).

Imports

KernelDocDirective

wrong

from linuxdoc import KernelDocDirective

correct

from linuxdoc.kernel_doc import KernelDocDirective

KernelDocDirective is in the kernel_doc submodule, not top-level.

linuxdoc_extension
```
from linuxdoc import linuxdoc_extension
```
Direct extension used in conf.py.

Quickstart

Minimal conf.py setup to enable linuxdoc extension and kernel-doc directive.

# conf.py
from linuxdoc import linuxdoc_extension
extensions = ['linuxdoc.linuxdoc_extension']
# Also register kernel-doc directive
from linuxdoc.kernel_doc import KernelDocDirective
def setup(app):
    app.add_directive('kernel-doc', KernelDocDirective)