Documentation: Use Sphinx doxylink to generate links to doxygen
The libcamera Sphinx documentation needs to link to the API documentation generated by Doxygen. The links currently point to the documentation hosted on the official https://libcamera.org/ website. This causes multiple issues: - Doxygen generates URLs with MD5 hashes of function signatures, making the link targets unstable. - When testing documentation builds that include API changes, links to new API elements will be broken. - The generated documentation can't be browsed offline. Fix this by using the Sphinx doxylink extension. This allows specifying link targets as class and function names, with the link being automatically generated using the same MD5 hashing as Doxygen. The root of the link target is configured in a central location, which defaults to the build directory and can be overridden to point to the libcamera website when pushing the documentation. This commit only introduces the infrastructure to use doxylink. Manual links will be replaced separately. Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Reviewed-by: Stefan Klug <stefan.klug@ideasonboard.com>
This commit is contained in:
Laurent Pinchart
@@ -3,6 +3,8 @@
|
||||
@INCLUDE_PATH = @TOP_BUILDDIR@/Documentation
|
||||
@INCLUDE = Doxyfile-common
|
||||
|
||||
GENERATE_TAGFILE = @TOP_BUILDDIR@/Documentation/internal-api-html/tagfile.xml
|
||||
|
||||
HIDE_UNDOC_CLASSES = NO
|
||||
HIDE_UNDOC_MEMBERS = NO
|
||||
HTML_OUTPUT = internal-api-html
|
||||
|
||||
@@ -3,6 +3,8 @@
|
||||
@INCLUDE_PATH = @TOP_BUILDDIR@/Documentation
|
||||
@INCLUDE = Doxyfile-common
|
||||
|
||||
GENERATE_TAGFILE = @TOP_BUILDDIR@/Documentation/api-html/tagfile.xml
|
||||
|
||||
HIDE_UNDOC_CLASSES = YES
|
||||
HIDE_UNDOC_MEMBERS = YES
|
||||
HTML_OUTPUT = api-html
|
||||
|
||||
@@ -37,7 +37,8 @@ author = 'The libcamera documentation authors'
|
||||
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
|
||||
# ones.
|
||||
extensions = [
|
||||
'sphinx.ext.graphviz'
|
||||
'sphinx.ext.graphviz',
|
||||
'sphinxcontrib.doxylink',
|
||||
]
|
||||
|
||||
graphviz_output_format = 'svg'
|
||||
@@ -71,6 +72,16 @@ exclude_patterns = [
|
||||
# The name of the Pygments (syntax highlighting) style to use.
|
||||
pygments_style = None
|
||||
|
||||
doxylink = {
|
||||
'doxy-pub': (
|
||||
'Documentation/api-html/tagfile.xml',
|
||||
'../api-html/',
|
||||
),
|
||||
'doxy-int': (
|
||||
'Documentation/internal-api-html/tagfile.xml',
|
||||
'../internal-api-html/',
|
||||
),
|
||||
}
|
||||
|
||||
# -- Options for HTML output -------------------------------------------------
|
||||
|
||||
|
||||
@@ -81,16 +81,16 @@ if doxygen.found() and dot.found()
|
||||
'@INPUT@',
|
||||
])
|
||||
|
||||
custom_target('doxygen-public',
|
||||
input : [
|
||||
doxyfile,
|
||||
doxyfile_common,
|
||||
],
|
||||
output : 'api-html',
|
||||
command : [doxygen, doxyfile],
|
||||
install : true,
|
||||
install_dir : doc_install_dir,
|
||||
install_tag : 'doc')
|
||||
doxygen_public = custom_target('doxygen-public',
|
||||
input : [
|
||||
doxyfile,
|
||||
doxyfile_common,
|
||||
],
|
||||
output : 'api-html',
|
||||
command : [doxygen, doxyfile],
|
||||
install : true,
|
||||
install_dir : doc_install_dir,
|
||||
install_tag : 'doc')
|
||||
|
||||
# This is the internal documentation, which hard-codes a list of directories
|
||||
# to parse in its doxyfile.
|
||||
@@ -99,18 +99,18 @@ if doxygen.found() and dot.found()
|
||||
output : 'Doxyfile-internal',
|
||||
configuration : cdata)
|
||||
|
||||
custom_target('doxygen-internal',
|
||||
input : [
|
||||
doxyfile,
|
||||
doxyfile_common,
|
||||
doxygen_public_input,
|
||||
doxygen_internal_input,
|
||||
],
|
||||
output : 'internal-api-html',
|
||||
command : [doxygen, doxyfile],
|
||||
install : true,
|
||||
install_dir : doc_install_dir,
|
||||
install_tag : 'doc-internal')
|
||||
doxygen_internal = custom_target('doxygen-internal',
|
||||
input : [
|
||||
doxyfile,
|
||||
doxyfile_common,
|
||||
doxygen_public_input,
|
||||
doxygen_internal_input,
|
||||
],
|
||||
output : 'internal-api-html',
|
||||
command : [doxygen, doxyfile],
|
||||
install : true,
|
||||
install_dir : doc_install_dir,
|
||||
install_tag : 'doc-internal')
|
||||
endif
|
||||
|
||||
#
|
||||
@@ -121,6 +121,27 @@ sphinx = find_program('sphinx-build-3', 'sphinx-build',
|
||||
required : get_option('documentation'))
|
||||
|
||||
if sphinx.found()
|
||||
# Many distributions do not provide a recent-enough version of the doxylink
|
||||
# module. This results in a build error with a cryptic message. Check the
|
||||
# version manually and print clear error messages.
|
||||
py_mod = import('python')
|
||||
py3 = py_mod.find_installation('python3')
|
||||
|
||||
mod = 'sphinxcontrib.doxylink'
|
||||
min_version = '>=1.6.1'
|
||||
version = run_command(py3, '-c',
|
||||
'import @0@ ; print(@0@.__version__)'.format(mod),
|
||||
check : false).stdout().strip()
|
||||
|
||||
if version == ''
|
||||
error('@0@ module not found'.format(mod))
|
||||
endif
|
||||
|
||||
if not version.version_compare(min_version)
|
||||
error('@0@ module v@1@ is too old, @2@ is needed'
|
||||
.format(mod, version, min_version))
|
||||
endif
|
||||
|
||||
docs_sources = [
|
||||
'camera-sensor-model.rst',
|
||||
'code-of-conduct.rst',
|
||||
@@ -154,6 +175,10 @@ if sphinx.found()
|
||||
input : docs_sources,
|
||||
output : 'html',
|
||||
build_by_default : true,
|
||||
depends : [
|
||||
doxygen_public,
|
||||
doxygen_internal,
|
||||
],
|
||||
install : true,
|
||||
install_dir : doc_install_dir,
|
||||
install_tag : 'doc')
|
||||
|
||||
@@ -67,7 +67,8 @@ for device hotplug enumeration: [optional]
|
||||
libudev-dev
|
||||
|
||||
for documentation: [optional]
|
||||
python3-sphinx doxygen graphviz texlive-latex-extra
|
||||
doxygen graphviz python3-sphinx python3-sphinxcontrib.doxylink (>= 1.6.1)
|
||||
texlive-latex-extra
|
||||
|
||||
for gstreamer: [optional]
|
||||
libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev
|
||||
|
||||
Reference in New Issue
Block a user