@@ -9,14 +9,8 @@
# -- Path setup --------------------------------------------------------------
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
-
+import sys
+sys.path.insert(0, "@CURRENT_SRCDIR@/extensions")
# -- Project information -----------------------------------------------------
@@ -39,6 +33,7 @@ author = 'The libcamera documentation authors'
extensions = [
'sphinx.ext.graphviz',
'sphinxcontrib.doxylink',
+ 'doxygen-link',
]
graphviz_output_format = 'svg'
@@ -75,14 +70,25 @@ pygments_style = None
doxylink = {
'doxy-pub': (
'@TOP_BUILDDIR@/Documentation/api-html/tagfile.xml',
- '../api-html/',
+ 'api-html/',
),
'doxy-int': (
'@TOP_BUILDDIR@/Documentation/internal-api-html/tagfile.xml',
- '../internal-api-html/',
+ 'internal-api-html/',
),
}
+doxygen_links = [
+ [
+ '@TOP_BUILDDIR@/Documentation/html/api-html',
+ '@TOP_BUILDDIR@/Documentation/api-html',
+ ],
+ [
+ '@TOP_BUILDDIR@/Documentation/html/internal-api-html',
+ '@TOP_BUILDDIR@/Documentation/internal-api-html',
+ ],
+]
+
# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
new file mode 100644
@@ -0,0 +1,73 @@
+# SPDX-License-Identifier: GPL-2.0-or-later
+# Copyright (C) 2025, Ideas on Board Oy
+
+import contextlib
+import os
+import shutil
+from pathlib import Path
+from sphinx.util import logging
+
+__version__ = "0.0.0"
+
+logger = logging.getLogger(__name__)
+
+
+def on_config_inited(app, config):
+ entries = []
+
+ outdir = Path(app.outdir).absolute()
+
+ for index, items in enumerate(config.doxygen_links):
+ err_msg_prefix = f'Config variable `doxygen_links` contains invalid entry {index} (`{items}`)'
+
+ if len(items) != 2:
+ raise ValueError(f'{err_msg_prefix}: expected (path, target)')
+
+ path = Path(items[0]).absolute()
+ target = Path(items[1]).relative_to(path.parent, walk_up=True)
+
+ if not path.is_relative_to(outdir):
+ raise ValueError(f'{err_msg_prefix}: path `{items[0]}` is outside of output directory `{outdir}`')
+
+ entries.append([path, target])
+
+ config.doxygen_links = entries
+
+
+def on_builder_inited(app):
+ # Remove the symlinks if they exist, to avoid overwriting the index.html
+ # generated by Doxygen with the placeholder index from Sphinx.
+
+ for path, target in app.config.doxygen_links:
+ if path.is_symlink():
+ logger.info(f'Removing existing symlink {path}')
+ os.unlink(path)
+
+
+def on_build_finished(app, exc):
+ # Create the symlinks. Remove any existing placeholder directory
+ # recursively first.
+
+ if exc:
+ return
+
+ for path, target in app.config.doxygen_links:
+ logger.info(f'Creating symlink {path} -> {target}')
+
+ if path.is_dir():
+ shutil.rmtree(path)
+
+ os.symlink(target, path)
+
+
+def setup(app):
+ app.add_config_value('doxygen_links', [], 'env', frozenset({list, tuple}))
+ app.connect('config-inited', on_config_inited)
+ app.connect('builder-inited', on_builder_inited)
+ app.connect('build-finished', on_build_finished)
+
+ return {
+ "version": __version__,
+ "parallel_read_safe": True,
+ "parallel_write_safe": True,
+ }
@@ -12,6 +12,7 @@ dot = find_program('dot', required : get_option('documentation'))
if doxygen.found() and dot.found()
cdata = configuration_data()
cdata.set('VERSION', 'v@0@'.format(libcamera_git_version))
+ cdata.set('CURRENT_SRCDIR', meson.current_source_dir())
cdata.set('TOP_SRCDIR', meson.project_source_root())
cdata.set('TOP_BUILDDIR', meson.project_build_root())
cdata.set('OUTPUT_DIR', meson.current_build_dir())
@@ -89,7 +90,7 @@ if doxygen.found() and dot.found()
output : 'api-html',
command : [doxygen, doxyfile],
install : true,
- install_dir : doc_install_dir,
+ install_dir : doc_install_dir / 'html',
install_tag : 'doc')
# This is the internal documentation, which hard-codes a list of directories
@@ -109,7 +110,7 @@ if doxygen.found() and dot.found()
output : 'internal-api-html',
command : [doxygen, doxyfile],
install : true,
- install_dir : doc_install_dir,
+ install_dir : doc_install_dir / 'html',
install_tag : 'doc-internal')
endif
@@ -149,7 +150,11 @@ if sphinx.found()
fs = import('fs')
sphinx_conf_dir = fs.parent(sphinx_conf)
+ sphinx_env = environment()
+ sphinx_env.set('PYTHONDONTWRITEBYTECODE', '1')
+
docs_sources = [
+ 'api-html/index.rst',
'camera-sensor-model.rst',
'code-of-conduct.rst',
'coding-style.rst',
@@ -164,6 +169,7 @@ if sphinx.found()
'guides/pipeline-handler.rst',
'guides/tracing.rst',
'index.rst',
+ 'internal-api-html/index.rst',
'introduction.rst',
'lens_driver_requirements.rst',
'libcamera_architecture.rst',
@@ -183,10 +189,14 @@ if sphinx.found()
input : docs_sources,
output : 'html',
build_by_default : true,
+ depend_files : [
+ 'extensions/doxygen-link.py',
+ ],
depends : [
doxygen_public,
doxygen_internal,
],
+ env : sphinx_env,
install : true,
install_dir : doc_install_dir,
install_tag : 'doc')
@@ -195,7 +205,8 @@ if sphinx.found()
command : [sphinx, '-W', '-b', 'linkcheck',
'-c', sphinx_conf_dir,
meson.current_source_dir(), '@OUTPUT@'],
- build_always_stale : true,
input : docs_sources,
- output : 'linkcheck')
+ output : 'linkcheck',
+ build_always_stale : true,
+ env : sphinx_env)
endif
The libcamera documentation is made of high-level documentation and guides, written as ReStructuredText and compiled to HTML by Sphinx, and API reference documentation, written as comments in the code and compiled to HTML by Doxygen. Due to meson limitations that make it difficult to place output files in subdirectories, the compilation process produces an html/ directory for the Sphinx documentation, and api-html/ and internal-api-html/ directories for the Doxygen documentation. When deploying the documentation to the libcamera.org website, the api-html and internal-api-html/ directories are moved within html/ to make the documentation self-contained. The Sphinx and Doxygen documentation link to each other. The links are generated using relative paths, based on the directory hierarchy on the website. This makes them broken when navigating the documentation in the build tree or in the directory where libcamera is installed. Fix this by standardizing on the directories hierarchy of the website in the build and install directories: - For the build directory, we can't easily build the Doxygen documentation in a subdirectory of the Sphinx documentation due to limitations of meson. Keep the existing output directories, and replace the html/api-html/ and html/internal-api-html/ placeholder directories with symlinks to the Doxygen output directories. This is handled by a small custom Sphinx extension. - For the install directory, install the Doxygen documentation to html/api-html/ and html/internal-api-html/. This overwrites the placeholders. Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> --- Changes since v1: - Split from "[PATCH 4/6] documentation: Include API docs in the sphinx documentation" - Avoid copying the doxygen documentation - Use a sphinx extension to generate symlinks --- Documentation/conf.py.in | 26 +++++---- Documentation/extensions/doxygen-link.py | 73 ++++++++++++++++++++++++ Documentation/meson.build | 19 ++++-- 3 files changed, 104 insertions(+), 14 deletions(-) create mode 100644 Documentation/extensions/doxygen-link.py