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

Message ID 20250908140803.123272-5-stefan.klug@ideasonboard.com
State Superseded
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(-)

Comments

Laurent Pinchart Sept. 10, 2025, 5:26 p.m. UTC | #1
On Mon, Sep 08, 2025 at 04:07:47PM +0200, Stefan Klug wrote:
> This commit prepares the move of all the libcamera documetation to a

s/documetation/documentation/

> 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(-)
> 
> 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>

s/Public-API/Public API/

or maybe "Pulic API Reference" as written today on the website.

> +
> +.. toctree::
> +   :maxdepth: 1
> +   :caption: For Developers

I expect the "users" in the above category to also be developers. I'm
not sure how to best name those two categories though. This can be
improved later.

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

s/Internal-API/Internal API/

>  
>  .. 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())

This belongs to patch 2/6.

>      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',
> +
> +

A single blank line should be enough.

> +    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,
> -                  ],
> +                  ])

Why is this not installed anymore ?

> +
> +    custom_target('documentation',
> +                  command : ['cp', '-r', '@OUTDIR@/api-html', '@OUTDIR@/internal-api-html', '@OUTDIR@/html'],

That's not very nice :-/ Could we avoid the copy ? It's not clear from
the commit message why you need to do so.

> +                  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')
Laurent Pinchart Sept. 10, 2025, 5:41 p.m. UTC | #2
On Mon, Sep 08, 2025 at 04:07:47PM +0200, Stefan Klug wrote:
> 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(-)
> 
> 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',

The 'output' argument is specified twice.

>                    install : true,
>                    install_dir : doc_install_dir,
>                    install_tag : 'doc')

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')