[4/6] documentation: Include API docs in the sphinx documentation
diff mbox series

Message ID 20250908140803.123272-5-stefan.klug@ideasonboard.com
State New
Headers show
Series
  • Documentation theming update
Related show

Commit Message

Stefan Klug Sept. 8, 2025, 2:07 p.m. UTC 
This commit prepares the move of all the libcamera documetation to a
place separate from the website. This makes it easier to handle website
and docs separately.

The index is updated to mimic the structure currently available on the
website.

The build process now first creates the sphinx documentation and then
copies the doxygen documentation into the sphinx output directory.

Signed-off-by: Stefan Klug <stefan.klug@ideasonboard.com>

---

ToDo:
- The meson custom targets still need some love. We need to decide what
  gets installed and in what structure.
---
 Documentation/conf.py.in       |  4 ++--
 Documentation/index.rst        | 31 +++++++++++++++++++------------
 Documentation/introduction.rst |  6 ------
 Documentation/meson.build      | 21 +++++++++++++++++----
 4 files changed, 38 insertions(+), 24 deletions(-)

Patch
diff mbox series 

diff --git a/Documentation/conf.py.in b/Documentation/conf.py.in
index 44e9aaf133ef..c772f643fb7c 100644
--- a/Documentation/conf.py.in
+++ b/Documentation/conf.py.in
@@ -75,11 +75,11 @@  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/',
     ),
 }
 
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 251112fbdf5f..f6b9994c58c4 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -4,28 +4,35 @@ 
 
 .. toctree::
    :maxdepth: 1
-   :caption: Contents:
+   :caption: For Users
+
+   Introduction <self>
+   Feature Requirements <feature_requirements>
+   Application Writer's Guide <guides/application-developer>
+   Python Bindings <python-bindings>
+   Environment variables <environment_variables>
+   Public-API <api-html/index>
+
+.. toctree::
+   :maxdepth: 1
+   :caption: For Developers
 
-   Home <self>
    Contribute <contributing>
    Getting Started <getting-started>
-
-   Application Writer's Guide <guides/application-developer>
    Camera Sensor Model <camera-sensor-model>
-   Environment variables <environment_variables>
-   Feature Requirements <feature_requirements>
    IPA Writer's guide <guides/ipa>
-   Lens driver requirements <lens_driver_requirements>
    libcamera Architecture <libcamera_architecture>
    Pipeline Handler Writer's Guide <guides/pipeline-handler>
-   Python Bindings <python-bindings>
-   Sensor driver requirements <sensor_driver_requirements>
    SoftwareISP Benchmarking <software-isp-benchmarking>
    Tracing guide <guides/tracing>
-
    Design document: AE <design/ae>
+   Internal-API <internal-api-html/index>
 
 .. toctree::
-   :hidden:
+   :maxdepth: 1
+   :caption: For System Integrators
+
+   Lens driver requirements <lens_driver_requirements>
+   Sensor driver requirements <sensor_driver_requirements>
+
 
-   introduction
diff --git a/Documentation/introduction.rst b/Documentation/introduction.rst
index 82aa11a30f33..d76cebd05ee1 100644
--- a/Documentation/introduction.rst
+++ b/Documentation/introduction.rst
@@ -6,12 +6,6 @@ 
 Introduction
 ************
 
-.. toctree::
-   :hidden:
-
-   API <api-html/index>
-   Internal API <internal-api-html/index>
-
 What is libcamera?
 ==================
 
diff --git a/Documentation/meson.build b/Documentation/meson.build
index f73407432fff..f9d17935749f 100644
--- a/Documentation/meson.build
+++ b/Documentation/meson.build
@@ -13,6 +13,7 @@  if doxygen.found() and dot.found()
     cdata = configuration_data()
     cdata.set('VERSION', 'v@0@'.format(libcamera_git_version))
     cdata.set('TOP_SRCDIR', meson.project_source_root())
+    cdata.set('CURRENT_SRCDIR', meson.current_source_dir())
     cdata.set('TOP_BUILDDIR', meson.project_build_root())
     cdata.set('OUTPUT_DIR', meson.current_build_dir())
     cdata.set('WARN_AS_ERROR', get_option('doc_werror') ? 'YES' : 'NO')
@@ -150,6 +151,7 @@  if sphinx.found()
     sphinx_conf_dir = fs.parent(sphinx_conf)
 
     docs_sources = [
+        'api-html/index.rst',
         'camera-sensor-model.rst',
         'code-of-conduct.rst',
         'coding-style.rst',
@@ -164,6 +166,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',
@@ -176,17 +179,27 @@  if sphinx.found()
 
     release = 'release=v' + libcamera_git_version
 
-    custom_target('documentation',
+
+
+    documentation_sphinx = custom_target('documentation-sphinx',
                   command : [sphinx, '-D', release, '-q', '-W', '-b', 'html',
                              '-c', sphinx_conf_dir,
-                             meson.current_source_dir(), '@OUTPUT@'],
+                             meson.current_source_dir(), '@OUTDIR@/html'],
                   input : docs_sources,
-                  output : 'html',
+                  output: 'sphinx-build',
                   build_by_default : true,
                   depends : [
                       doxygen_public,
                       doxygen_internal,
-                  ],
+                  ])
+
+    custom_target('documentation',
+                  command : ['cp', '-r', '@OUTDIR@/api-html', '@OUTDIR@/internal-api-html', '@OUTDIR@/html'],
+                  output : 'html',
+                  depends: [documentation_sphinx],
+                  build_by_default : true,
+                  build_always_stale : true,
+                  output: 'html',
                   install : true,
                   install_dir : doc_install_dir,
                   install_tag : 'doc')