Sphinx Devhelp Extension

2.0.0 · active · verified Sun Mar 29

sphinxcontrib-devhelp is a Sphinx extension that generates Devhelp documents (a documentation format used by the GNOME desktop environment) alongside standard HTML documentation. It is currently at version 2.0.0 and typically aligns its major releases with those of Sphinx itself, ensuring compatibility with the latest Sphinx features and Python versions.

Warnings

breaking Version 2.0.0 (and Sphinx 2.0.0 which it follows) dropped support for Python 2.7, Python 3.4, and Docutils 0.11. This extension now requires Python >=3.9.
Fix: Upgrade your Python environment to 3.9 or newer and ensure Docutils is up-to-date. If these are not possible, use an older version of `sphinxcontrib-devhelp` compatible with your environment.
breaking Prior to Sphinx 2.0.0, `sphinxcontrib-devhelp` was often bundled directly with Sphinx. With Sphinx 2.0.0 and later, it became a separate, explicitly installable package.
Fix: Projects using Sphinx 2.0.0 or newer must explicitly `pip install sphinxcontrib-devhelp` as it is no longer included by default.
gotcha Generating Devhelp documents requires invoking the dedicated `devhelp` builder. Standard `html` builds will not produce Devhelp output.
Fix: Use the command `sphinx-build -b devhelp path/to/source path/to/build/devhelp` or run `make devhelp` if you use a standard Sphinx Makefile.
gotcha After building, the generated Devhelp documents are not automatically registered with the Devhelp application. They need to be manually linked or placed in a specific directory for Devhelp to find them.
Fix: Refer to the output message from the Devhelp builder (its 'epilog') for instructions, which typically involve creating a symlink: `mkdir -p $HOME/.local/share/devhelp/books && ln -s $PWD/path/to/build/devhelp $HOME/.local/share/devhelp/books/YourProjectName && devhelp`.

Install

pip install sphinxcontrib-devhelp Install latest version

Imports

sphinxcontrib.devhelp
```
extensions = ['sphinxcontrib.devhelp']
```
Sphinx extensions are configured by adding their full dotted name to the `extensions` list within your project's `conf.py` file, not via a standard Python `import` statement in the file itself.

Quickstart

After installing the package, enable the extension by adding `sphinxcontrib.devhelp` to the `extensions` list in your Sphinx project's `conf.py`. Then, build the documentation using the `devhelp` builder. You might need to replace `doc/source` and `doc/build/devhelp` with your actual source and build directories.

# conf.py

# ... (other Sphinx configurations)

# Add 'sphinxcontrib.devhelp' to your extensions list
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',
    'sphinxcontrib.devhelp',
]

# Optional: Configure the basename for the Devhelp output
devhelp_basename = 'MyProjectDevhelp'

# Build from terminal
# In your Sphinx project's root directory:
# sphinx-build -b devhelp doc/source doc/build/devhelp

view raw JSON →