Merge branch 'master' into next

Author: naushir

Documentation/Doxyfile-internal.in

@@ -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

Documentation/Doxyfile-public.in

@@ -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

Documentation/conf.py renamed to Documentation/conf.py.in

@@ -21,8 +21,8 @@
 # -- Project information -----------------------------------------------------
 
 project = 'libcamera'
-copyright = '2018-2019, The libcamera documentation authors'
-author = u'Kieran Bingham, Jacopo Mondi, Laurent Pinchart, Niklas Söderlund'
+copyright = '2018-2025, The libcamera documentation authors'
+author = 'The libcamera documentation authors'
 
 # Version information is provided by the build environment, through the
 # sphinx command line.
@@ -37,7 +37,8 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'sphinx.ext.graphviz'
+    'sphinx.ext.graphviz',
+    'sphinxcontrib.doxylink',
 ]
 
 graphviz_output_format = 'svg'
@@ -65,23 +66,30 @@
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = [
-    '_build',
-    'Thumbs.db',
-    '.DS_Store',
     'documentation-contents.rst',
 ]
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = None
 
+doxylink = {
+    'doxy-pub': (
+        '@TOP_BUILDDIR@/Documentation/api-html/tagfile.xml',
+        '../api-html/',
+    ),
+    'doxy-int': (
+        '@TOP_BUILDDIR@/Documentation/internal-api-html/tagfile.xml',
+        '../internal-api-html/',
+    ),
+}
 
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
 html_theme = 'theme'
-html_theme_path = ['.']
+html_theme_path = ['@THEME_DIR@']
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -103,78 +111,3 @@
 # 'searchbox.html']``.
 #
 # html_sidebars = {}
-
-
-# -- Options for HTMLHelp output ---------------------------------------------
-
-# Output file base name for HTML help builder.
-htmlhelp_basename = 'libcameradoc'
-
-
-# -- Options for LaTeX output ------------------------------------------------
-
-latex_elements = {
-    # The paper size ('letterpaper' or 'a4paper').
-    #
-    # 'papersize': 'letterpaper',
-
-    # The font size ('10pt', '11pt' or '12pt').
-    #
-    # 'pointsize': '10pt',
-
-    # Additional stuff for the LaTeX preamble.
-    #
-    # 'preamble': '',
-
-    # Latex figure (float) alignment
-    #
-    # 'figure_align': 'htbp',
-}
-
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title,
-#  author, documentclass [howto, manual, or own class]).
-latex_documents = [
-    (master_doc, 'libcamera.tex', 'libcamera Documentation',
-     author, 'manual'),
-]
-
-
-# -- Options for manual page output ------------------------------------------
-
-# One entry per manual page. List of tuples
-# (source start file, name, description, authors, manual section).
-man_pages = [
-    (master_doc, 'libcamera', 'libcamera Documentation',
-     [author], 1)
-]
-
-
-# -- Options for Texinfo output ----------------------------------------------
-
-# Grouping the document tree into Texinfo files. List of tuples
-# (source start file, target name, title, author,
-#  dir menu entry, description, category)
-texinfo_documents = [
-    (master_doc, 'libcamera', 'libcamera Documentation',
-     author, 'libcamera', 'One line description of project.',
-     'Miscellaneous'),
-]
-
-
-# -- Options for Epub output -------------------------------------------------
-
-# Bibliographic Dublin Core info.
-epub_title = project
-
-# The unique identifier of the text. This can be a ISBN number
-# or the project homepage.
-#
-# epub_identifier = ''
-
-# A unique identification for the text.
-#
-# epub_uid = ''
-
-# A list of files that should not be packed into the epub file.
-epub_exclude_files = ['search.html']

Documentation/environment_variables.rst

@@ -90,7 +90,7 @@ The optional `category <Log categories_>`__ is a string matching the categories
 defined by each file in the source base using the logging infrastructure. It
 can include a wildcard ('*') character at the end to match multiple categories.
 
-For more information refer to the `API documentation <https://libcamera.org/api-html/log_8h.html#details>`__.
+For more information refer to the :doxy-int:`API documentation <log.h>`.
 
 Examples:
 

Documentation/guides/application-developer.rst

@@ -46,15 +46,14 @@ defined names and types without the need of prefixing them.
 Camera Manager
 --------------
 
-Every libcamera-based application needs an instance of a `CameraManager`_ that
-runs for the life of the application. When the Camera Manager starts, it
+Every libcamera-based application needs an instance of a :doxy-pub:`CameraManager`
+that runs for the life of the application. When the Camera Manager starts, it
 enumerates all the cameras detected in the system. Behind the scenes, libcamera
 abstracts and manages the complex pipelines that kernel drivers expose through
 the `Linux Media Controller`_ and `Video for Linux`_ (V4L2) APIs, meaning that
 an application doesn't need to handle device or driver specific details.
 
-.. _CameraManager: https://libcamera.org/api-html/classlibcamera_1_1CameraManager.html
-.. _Linux Media Controller: https://www.kernel.org/doc/html/latest/media/uapi/mediactl/media-controller-intro.html
+.. _Linux Media Controller: https://www.kernel.org/doc/html/latest/userspace-api/media/mediactl/media-controller.html
 .. _Video for Linux: https://www.linuxtv.org/docs.php
 
 Before the ``int main()`` function, create a global shared pointer
@@ -210,10 +209,9 @@ function. If the new values are not supported by the ``Camera`` device, the
 validation process adjusts the parameters to what it considers to be the closest
 supported values.
 
-The ``validate`` function returns a `Status`_ which applications shall check to
-see if the Pipeline Handler adjusted the configuration.
-
-.. _Status: https://libcamera.org/api-html/classlibcamera_1_1CameraConfiguration.html#a64163f21db2fe1ce0a6af5a6f6847744
+The ``validate`` function returns a :doxy-pub:`CameraConfiguration::Status`
+which applications shall check to see if the Pipeline Handler adjusted the
+configuration.
 
 For example, the code above set the width and height to 640x480, but if the
 camera cannot produce an image that large, it might adjust the configuration to
@@ -348,10 +346,10 @@ camera device, and associate a buffer for each of them for the ``Stream``.
 Event handling and callbacks
 ----------------------------
 
-The libcamera library uses the concept of `signals and slots` (similar to `Qt
-Signals and Slots`_) to connect events with callbacks to handle them.
+The libcamera library uses the concept of :doxy-pub:`signals and slots <Signal>`
+(similar to `Qt Signals and Slots`_) to connect events with callbacks to handle
+them.
 
-.. _signals and slots: https://libcamera.org/api-html/classlibcamera_1_1Signal.html#details
 .. _Qt Signals and Slots: https://doc.qt.io/qt-6/signalsandslots.html
 
 The ``Camera`` device emits two signals that applications can connect to in
@@ -400,9 +398,7 @@ Request completion events can be emitted for requests which have been canceled,
 for example, by unexpected application shutdown. To avoid an application
 processing invalid image data, it's worth checking that the request has
 completed successfully. The list of request completion statuses is available in
-the `Request::Status`_ class enum documentation.
-
-.. _Request::Status: https://www.libcamera.org/api-html/classlibcamera_1_1Request.html#a2209ba8d51af8167b25f6e3e94d5c45b
+the :doxy-pub:`Request::Status` class enum documentation.
 
 .. code:: cpp
 
@@ -422,9 +418,7 @@ Iterating through the map allows applications to inspect each completed buffer
 in this request, and access the metadata associated to each frame.
 
 The metadata buffer contains information such the capture status, a timestamp,
-and the bytes used, as described in the `FrameMetadata`_ documentation.
-
-.. _FrameMetaData: https://libcamera.org/api-html/structlibcamera_1_1FrameMetadata.html
+and the bytes used, as described in the :doxy-pub:`FrameMetadata` documentation.
 
 .. code:: cpp
 
@@ -515,13 +509,11 @@ and queue all the previously created requests.
 Event processing
 ~~~~~~~~~~~~~~~~
 
-libcamera creates an internal execution thread at `CameraManager::start()`_
+libcamera creates an internal execution thread at :doxy-pub:`CameraManager::start()`
 time to decouple its own event processing from the application's main thread.
 Applications are thus free to manage their own execution opportunely, and only
 need to respond to events generated by libcamera emitted through signals.
 
-.. _CameraManager::start(): https://libcamera.org/api-html/classlibcamera_1_1CameraManager.html#a49e322880a2a26013bb0076788b298c5
-
 Real-world applications will likely either integrate with the event loop of the
 framework they use, or create their own event loop to respond to user events.
 For the simple application presented in this example, it is enough to prevent