| Message ID | 20260512225505.234522-1-laurent.pinchart@ideasonboard.com |
|---|---|
| State | New |
| Headers | show |
| Series |
|
| Related | show |
Hi 2026. 05. 13. 0:55 keltezéssel, Laurent Pinchart írta: > We move the Doxygen-generated API documentation to the Sphinx output > directory at installation time, in order to integrate the two parts of > the documentation together. This uses a post-install script, arguably as > a hack, for lack of a better solution ([1]). > > The post-install step does not specify tags, which prevents it from > running when installing the doc or doc-internal tags only. To fix it, > split it in two runs, one for the public and one for the internal API, > and tag them with 'doc' and 'doc-internal' respectively. As the script > is now called with a single API directory, simplify it and make it print > a more precise message. > > [1] See commit 4a9863e05397 ("Documentation: Improve Sphinx and Doxygen > integration") for a more detailed explanation. > > Reported-by: Stefan Klug <stefan.klug@ideasonboard.com> > Closes: https://gitlab.freedesktop.org/camera/libcamera/-/work_items/333 > Suggested-by: Barnabás Pőcze <barnabas.pocze@ideasonboard.com> > Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> > --- > Documentation/install-doxygen.sh | 11 ++++------- > Documentation/meson.build | 6 ++++-- > 2 files changed, 8 insertions(+), 9 deletions(-) > > diff --git a/Documentation/install-doxygen.sh b/Documentation/install-doxygen.sh > index ea5a19dc8fda..091f356fe529 100755 > --- a/Documentation/install-doxygen.sh > +++ b/Documentation/install-doxygen.sh > @@ -7,12 +7,9 @@ > # Move Doxygen-generated API documentation to correct location > > doc_dir="${MESON_INSTALL_DESTDIR_PREFIX}/$1" > -shift > -dirs="$*" > +api_dir="$2" > > -echo "Moving API documentation" > +echo "Moving Doxygen ${api_dir} API documentation" > > -for dir in $dirs ; do > - rm -r "${doc_dir}/html/${dir}" > - mv "${doc_dir}/${dir}" "${doc_dir}/html/" > -done > +rm -r "${doc_dir}/html/${api_dir}" With only `--tags doc-internal`, this fails since `html` does not exist. Should this use `-rf` ? > +mv "${doc_dir}/${api_dir}" "${doc_dir}/html/" What should happen when only `--tags doc-internal` is used? Currently this copies the documentation right into `html/`. I suppose that is probably a reasonable choice. Or we can keep the `rm` invocation as is and let it fail -> `--tags doc-internal` only is considered unsupported. > diff --git a/Documentation/meson.build b/Documentation/meson.build > index 51899c19c166..84c05091d5b5 100644 > --- a/Documentation/meson.build > +++ b/Documentation/meson.build > @@ -194,8 +194,10 @@ if sphinx.found() > install_dir : doc_install_dir, > install_tag : 'doc') > > - meson.add_install_script('install-doxygen.sh', doc_install_dir, > - 'public-api', 'internal-api') > + meson.add_install_script('install-doxygen.sh', doc_install_dir, 'public-api', > + install_tag : 'doc') > + meson.add_install_script('install-doxygen.sh', doc_install_dir, 'internal-api', > + install_tag : 'doc-internal') > > custom_target('documentation-linkcheck', > command : [sphinx, '-W', '-b', 'linkcheck', > > base-commit: b0dbd5100b1b1665dd2bc839d06263d55a89a6bd
Hi, Quoting Barnabás Pőcze (2026-05-13 09:31:47) > Hi > > 2026. 05. 13. 0:55 keltezéssel, Laurent Pinchart írta: > > We move the Doxygen-generated API documentation to the Sphinx output > > directory at installation time, in order to integrate the two parts of > > the documentation together. This uses a post-install script, arguably as > > a hack, for lack of a better solution ([1]). > > > > The post-install step does not specify tags, which prevents it from > > running when installing the doc or doc-internal tags only. To fix it, > > split it in two runs, one for the public and one for the internal API, > > and tag them with 'doc' and 'doc-internal' respectively. As the script > > is now called with a single API directory, simplify it and make it print > > a more precise message. > > > > [1] See commit 4a9863e05397 ("Documentation: Improve Sphinx and Doxygen > > integration") for a more detailed explanation. > > > > Reported-by: Stefan Klug <stefan.klug@ideasonboard.com> > > Closes: https://gitlab.freedesktop.org/camera/libcamera/-/work_items/333 > > Suggested-by: Barnabás Pőcze <barnabas.pocze@ideasonboard.com> > > Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> > > --- > > Documentation/install-doxygen.sh | 11 ++++------- > > Documentation/meson.build | 6 ++++-- > > 2 files changed, 8 insertions(+), 9 deletions(-) > > > > diff --git a/Documentation/install-doxygen.sh b/Documentation/install-doxygen.sh > > index ea5a19dc8fda..091f356fe529 100755 > > --- a/Documentation/install-doxygen.sh > > +++ b/Documentation/install-doxygen.sh > > @@ -7,12 +7,9 @@ > > # Move Doxygen-generated API documentation to correct location > > > > doc_dir="${MESON_INSTALL_DESTDIR_PREFIX}/$1" > > -shift > > -dirs="$*" > > +api_dir="$2" > > > > -echo "Moving API documentation" > > +echo "Moving Doxygen ${api_dir} API documentation" > > > > -for dir in $dirs ; do > > - rm -r "${doc_dir}/html/${dir}" > > - mv "${doc_dir}/${dir}" "${doc_dir}/html/" > > -done > > +rm -r "${doc_dir}/html/${api_dir}" > > With only `--tags doc-internal`, this fails since `html` does not exist. > Should this use `-rf` ? I think that would be good. This script should not fail if it misses a file. > > > > +mv "${doc_dir}/${api_dir}" "${doc_dir}/html/" > > What should happen when only `--tags doc-internal` is used? Currently > this copies the documentation right into `html/`. I suppose that is > probably a reasonable choice. Or we can keep the `rm` invocation as is > and let it fail -> `--tags doc-internal` only is considered unsupported. I don't think we should install the internal docs directly into html. That will create a big mess, if someone accidentally did that and then installs with --tags doc. So I think we should add an unconditional mkdir -p ${doc_dir}/html at the beginning. Or what about dropping the doc-internal tag? Is there really a use-case where that is needed? The normal users will all just run 'meson install' without --tags and the professional users will likely want the internal docs also. Best regards, Stefan > > > > diff --git a/Documentation/meson.build b/Documentation/meson.build > > index 51899c19c166..84c05091d5b5 100644 > > --- a/Documentation/meson.build > > +++ b/Documentation/meson.build > > @@ -194,8 +194,10 @@ if sphinx.found() > > install_dir : doc_install_dir, > > install_tag : 'doc') > > > > - meson.add_install_script('install-doxygen.sh', doc_install_dir, > > - 'public-api', 'internal-api') > > + meson.add_install_script('install-doxygen.sh', doc_install_dir, 'public-api', > > + install_tag : 'doc') > > + meson.add_install_script('install-doxygen.sh', doc_install_dir, 'internal-api', > > + install_tag : 'doc-internal') > > > > custom_target('documentation-linkcheck', > > command : [sphinx, '-W', '-b', 'linkcheck', > > > > base-commit: b0dbd5100b1b1665dd2bc839d06263d55a89a6bd >
On Wed, May 13, 2026 at 09:52:17AM +0200, Stefan Klug wrote: > Quoting Barnabás Pőcze (2026-05-13 09:31:47) > > 2026. 05. 13. 0:55 keltezéssel, Laurent Pinchart írta: > > > We move the Doxygen-generated API documentation to the Sphinx output > > > directory at installation time, in order to integrate the two parts of > > > the documentation together. This uses a post-install script, arguably as > > > a hack, for lack of a better solution ([1]). > > > > > > The post-install step does not specify tags, which prevents it from > > > running when installing the doc or doc-internal tags only. To fix it, > > > split it in two runs, one for the public and one for the internal API, > > > and tag them with 'doc' and 'doc-internal' respectively. As the script > > > is now called with a single API directory, simplify it and make it print > > > a more precise message. > > > > > > [1] See commit 4a9863e05397 ("Documentation: Improve Sphinx and Doxygen > > > integration") for a more detailed explanation. > > > > > > Reported-by: Stefan Klug <stefan.klug@ideasonboard.com> > > > Closes: https://gitlab.freedesktop.org/camera/libcamera/-/work_items/333 > > > Suggested-by: Barnabás Pőcze <barnabas.pocze@ideasonboard.com> > > > Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> > > > --- > > > Documentation/install-doxygen.sh | 11 ++++------- > > > Documentation/meson.build | 6 ++++-- > > > 2 files changed, 8 insertions(+), 9 deletions(-) > > > > > > diff --git a/Documentation/install-doxygen.sh b/Documentation/install-doxygen.sh > > > index ea5a19dc8fda..091f356fe529 100755 > > > --- a/Documentation/install-doxygen.sh > > > +++ b/Documentation/install-doxygen.sh > > > @@ -7,12 +7,9 @@ > > > # Move Doxygen-generated API documentation to correct location > > > > > > doc_dir="${MESON_INSTALL_DESTDIR_PREFIX}/$1" > > > -shift > > > -dirs="$*" > > > +api_dir="$2" > > > > > > -echo "Moving API documentation" > > > +echo "Moving Doxygen ${api_dir} API documentation" > > > > > > -for dir in $dirs ; do > > > - rm -r "${doc_dir}/html/${dir}" > > > - mv "${doc_dir}/${dir}" "${doc_dir}/html/" > > > -done > > > +rm -r "${doc_dir}/html/${api_dir}" > > > > With only `--tags doc-internal`, this fails since `html` does not exist. > > Should this use `-rf` ? > > I think that would be good. This script should not fail if it misses a > file. > > > > +mv "${doc_dir}/${api_dir}" "${doc_dir}/html/" > > > > What should happen when only `--tags doc-internal` is used? Currently > > this copies the documentation right into `html/`. I suppose that is > > probably a reasonable choice. Or we can keep the `rm` invocation as is > > and let it fail -> `--tags doc-internal` only is considered unsupported. > > I don't think we should install the internal docs directly into html. > That will create a big mess, if someone accidentally did that and then > installs with --tags doc. > > So I think we should add an unconditional > mkdir -p ${doc_dir}/html > at the beginning. So I gave this a try: diff --git a/Documentation/install-doxygen.sh b/Documentation/install-doxygen.sh index 091f356fe529..0981e002787f 100755 --- a/Documentation/install-doxygen.sh +++ b/Documentation/install-doxygen.sh @@ -11,5 +11,6 @@ api_dir="$2" echo "Moving Doxygen ${api_dir} API documentation" -rm -r "${doc_dir}/html/${api_dir}" +mkdir -p "${doc_dir}/html/" +rm -rf "${doc_dir}/html/${api_dir}" mv "${doc_dir}/${api_dir}" "${doc_dir}/html/" Here's the result: $ meson setup --auto-features disabled \ -D pipelines=[] \ -D test=false \ -D documentation=enabled \ -D doc_werror=true \ build/doctest ... $ meson compile -C build/doctest/ documentation [...] [26/26] Generating Documentation/documentation with a custom command $ meson install -C build/doctest \ --tags doc-internal \ --destdir install \ --no-rebuild [...] Moving Doxygen internal-api API documentation $ ls -l build/doctest/install/usr/local/share/doc/libcamera-0.7.1/html/ total 180 drwxr-xr-x 3 laurent laurent 139264 May 13 15:40 internal-api $ meson install -C build/doctest \ --tags doc \ --destdir install \ --no-rebuild [...] Moving Doxygen public-api API documentation $ ls -l build/doctest/install/usr/local/share/doc/libcamera-0.7.1/html/ total 764 -rw-r--r-- 1 laurent laurent 26703 May 13 15:40 camera-sensor-model.html -rw-r--r-- 1 laurent laurent 21583 May 13 15:40 code-of-conduct.html -rw-r--r-- 1 laurent laurent 42563 May 13 15:40 coding-style.html -rw-r--r-- 1 laurent laurent 24843 May 13 15:40 contributing.html drwxr-xr-x 2 laurent laurent 29 May 13 15:41 design -rw-r--r-- 1 laurent laurent 25728 May 13 15:40 feature_requirements.html -rw-r--r-- 1 laurent laurent 13686 May 13 15:40 genindex.html -rw-r--r-- 1 laurent laurent 24587 May 13 15:40 getting-started.html drwxr-xr-x 2 laurent laurent 125 May 13 15:41 guides drwxr-xr-x 2 laurent laurent 4096 May 13 15:41 _images -rw-r--r-- 1 laurent laurent 34142 May 13 15:40 index.html drwxr-xr-x 3 laurent laurent 139264 May 13 15:41 internal-api -rw-r--r-- 1 laurent laurent 30900 May 13 15:40 introduction.html -rw-r--r-- 1 laurent laurent 23715 May 13 15:40 isp-feature-matrix.html -rw-r--r-- 1 laurent laurent 16271 May 13 15:40 lens_driver_requirements.html -rw-r--r-- 1 laurent laurent 30120 May 13 15:40 libcamera_architecture.html -rw-r--r-- 1 laurent laurent 990 May 13 15:40 objects.inv drwxr-xr-x 3 laurent laurent 28672 May 13 15:41 public-api -rw-r--r-- 1 laurent laurent 19906 May 13 15:40 python-bindings.html -rw-r--r-- 1 laurent laurent 37285 May 13 15:40 runtime_configuration.html -rw-r--r-- 1 laurent laurent 12738 May 13 15:40 search.html -rw-r--r-- 1 laurent laurent 49640 May 13 15:40 searchindex.js -rw-r--r-- 1 laurent laurent 20641 May 13 15:40 sensor_driver_requirements.html -rw-r--r-- 1 laurent laurent 15305 May 13 15:40 sensor-support.html -rw-r--r-- 1 laurent laurent 19656 May 13 15:40 software-isp-benchmarking.html drwxr-xr-x 6 laurent laurent 4096 May 13 15:41 _sources drwxr-xr-x 7 laurent laurent 4096 May 13 15:41 _static *But* there's a hidden bug there. The html/internal-api/index.html file is now the placeholder generated by Sphinx, overwritten when installing the 'doc' tag. > Or what about dropping the doc-internal tag? Is there really a use-case > where that is needed? The normal users will all just run 'meson install' > without --tags and the professional users will likely want the internal > docs also. The internal API documentation is meant for libcamera developers, while the public API documentation is meant for application developers. I would therefore expect distributions to package the latter but not the former. When working on libcamera itself, a developer will have access to the source code, there should be no reason for them to read documentation installed by the distribution. Given that the internal API will change much faster than the public API, anything provided by the distribution, even if the major version matches, will be outdated. That's why there's a doc-internal tag, to facilitate packaging of the public API documentation without the internal API. I'd be tempted to stop installing the internal API documentation completely. Is anyone consuming that documentation outside of the build directory ? I'll experiment with a different approach for the CI documentation build that will not require this patch. > > > diff --git a/Documentation/meson.build b/Documentation/meson.build > > > index 51899c19c166..84c05091d5b5 100644 > > > --- a/Documentation/meson.build > > > +++ b/Documentation/meson.build > > > @@ -194,8 +194,10 @@ if sphinx.found() > > > install_dir : doc_install_dir, > > > install_tag : 'doc') > > > > > > - meson.add_install_script('install-doxygen.sh', doc_install_dir, > > > - 'public-api', 'internal-api') > > > + meson.add_install_script('install-doxygen.sh', doc_install_dir, 'public-api', > > > + install_tag : 'doc') > > > + meson.add_install_script('install-doxygen.sh', doc_install_dir, 'internal-api', > > > + install_tag : 'doc-internal') > > > > > > custom_target('documentation-linkcheck', > > > command : [sphinx, '-W', '-b', 'linkcheck', > > > > > > base-commit: b0dbd5100b1b1665dd2bc839d06263d55a89a6bd
diff --git a/Documentation/install-doxygen.sh b/Documentation/install-doxygen.sh index ea5a19dc8fda..091f356fe529 100755 --- a/Documentation/install-doxygen.sh +++ b/Documentation/install-doxygen.sh @@ -7,12 +7,9 @@ # Move Doxygen-generated API documentation to correct location doc_dir="${MESON_INSTALL_DESTDIR_PREFIX}/$1" -shift -dirs="$*" +api_dir="$2" -echo "Moving API documentation" +echo "Moving Doxygen ${api_dir} API documentation" -for dir in $dirs ; do - rm -r "${doc_dir}/html/${dir}" - mv "${doc_dir}/${dir}" "${doc_dir}/html/" -done +rm -r "${doc_dir}/html/${api_dir}" +mv "${doc_dir}/${api_dir}" "${doc_dir}/html/" diff --git a/Documentation/meson.build b/Documentation/meson.build index 51899c19c166..84c05091d5b5 100644 --- a/Documentation/meson.build +++ b/Documentation/meson.build @@ -194,8 +194,10 @@ if sphinx.found() install_dir : doc_install_dir, install_tag : 'doc') - meson.add_install_script('install-doxygen.sh', doc_install_dir, - 'public-api', 'internal-api') + meson.add_install_script('install-doxygen.sh', doc_install_dir, 'public-api', + install_tag : 'doc') + meson.add_install_script('install-doxygen.sh', doc_install_dir, 'internal-api', + install_tag : 'doc-internal') custom_target('documentation-linkcheck', command : [sphinx, '-W', '-b', 'linkcheck',
We move the Doxygen-generated API documentation to the Sphinx output directory at installation time, in order to integrate the two parts of the documentation together. This uses a post-install script, arguably as a hack, for lack of a better solution ([1]). The post-install step does not specify tags, which prevents it from running when installing the doc or doc-internal tags only. To fix it, split it in two runs, one for the public and one for the internal API, and tag them with 'doc' and 'doc-internal' respectively. As the script is now called with a single API directory, simplify it and make it print a more precise message. [1] See commit 4a9863e05397 ("Documentation: Improve Sphinx and Doxygen integration") for a more detailed explanation. Reported-by: Stefan Klug <stefan.klug@ideasonboard.com> Closes: https://gitlab.freedesktop.org/camera/libcamera/-/work_items/333 Suggested-by: Barnabás Pőcze <barnabas.pocze@ideasonboard.com> Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> --- Documentation/install-doxygen.sh | 11 ++++------- Documentation/meson.build | 6 ++++-- 2 files changed, 8 insertions(+), 9 deletions(-) base-commit: b0dbd5100b1b1665dd2bc839d06263d55a89a6bd