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