sphinxcontrib-doxylink

1.13.0 verified Fri May 01 auth: no python

Sphinx extension for linking to Doxygen documentation. Version 1.13.0 supports Python >=3.7,<4.0. Release cadence is irregular, with fixes and maintenance updates. It parses Doxygen tag files to enable cross-references to Doxygen documentation elements (classes, functions, files, etc.) from Sphinx RST or MyST content.

pip install sphinxcontrib-doxylink

Common errors

error Extension 'doxylink' has no configuration key 'doxylink_config' ↓

cause Using the wrong configuration variable name in conf.py.

fix

Use 'doxylink' (a dict) instead of 'doxylink_config'.

error No module named 'sphinxcontrib.doxylink' ↓

cause The extension is not installed or is installed but not importable.

fix

Run 'pip install sphinxcontrib-doxylink' and ensure the Python environment is correct.

error Error reading tag file: FileNotFoundError ↓

cause The 'tag' path in the doxylink config points to a non-existent file.

fix

Verify the tag file exists. Use an absolute path or correct relative path from conf.py.

Warnings

gotcha The 'tag' file path must be absolute or relative to the Sphinx source directory. Relative paths are resolved from the directory containing conf.py. ↓

fix Use an absolute path or ensure the relative path is correct relative to conf.py.

gotcha The Doxygen tag file must be generated with 'GENERATE_TAGFILE = YES' in the Doxyfile. If the tag file is missing or malformed, no links will be created. ↓

fix Set GENERATE_TAGFILE = YES in Doxyfile and regenerate.

deprecated In version 1.12.0, the packaging was switched to Poetry. Users installing from source via pip should use 'pip install -e .' instead of 'python setup.py install'. ↓

fix Use 'pip install -e .' for editable installs.

breaking Cache version was introduced in 1.12.3. Old cached files may cause issues when upgrading; the extension will now re-parse the Doxygen tag file if the extension version changes. ↓

fix Clear the Sphinx cache (remove _build/.doctrees or build directory) after upgrading.

Imports

doxylink
wrong
```
extensions = ['doxylink']
```
correct
```
extensions = ['sphinxcontrib.doxylink']
```
The correct dotted module path is 'sphinxcontrib.doxylink'. Using just 'doxylink' will fail to load.
doxylink_...
wrong
```
doxylink_config = ...
```
correct
```
doxylink = {...} in conf.py
```
The configuration key is 'doxylink' (a dict), not 'doxylink_config'. Users often misname it.

Quickstart

Minimal configuration: define the doxylink dict with a project name, base URL for the generated Doxygen HTML, and the path to the Doxygen tag file. Then add the extension to Sphinx's extensions list.

# conf.py
import os

doxylink = {
    'project': 'MyProject',
    'url': 'https://example.com/doxygen/html',
    'tag': 'path/to/tagfile.xml',
    'enabled': True,
}

extensions = ['sphinxcontrib.doxylink']