[libcamera-devel] [PATCH v2 5/5] libcamera: Documentation: Improve doxygen main page

[Jacopo Mondi]

Hi Dan

On Fri, Jan 05, 2024 at 04:41:04PM +0000, Daniel Scally via libcamera-devel wrote:
> The "Main Page" of the doxygen generated API reference is currently
> totally empty. Expand it with some introductory text along with links
> to the developer's guide, application developer's guide and the
> pipeline and IPA module writer's guides.
>
> Provide an easy link to switch between the reduced public reference
> pages and the more complete internal ones.
>
> Signed-off-by: Daniel Scally <dan.scally at ideasonboard.com>
> ---
> Changes in v2:
>
> 	- Changed the first paragraph to be more about what the documentation is
> 	than isn't (Jacopo)
> 	- Pushed the links to the guides into the \if internal block so that
> 	only the relevant one is presented.
>
>  Documentation/Doxyfile.in   |  1 +
>  Documentation/libcamera.dox | 33 +++++++++++++++++++++++++++++++++

Is 'libcamera.dox' selected as main page because the file name matches
the project name ? Just out of curiosity..

The text looks good to me, thanks!

Reviewed-by: Jacopo Mondi <jacopo.mondi at ideasonboard.com>


>  Documentation/meson.build   |  2 ++
>  3 files changed, 36 insertions(+)
>  create mode 100644 Documentation/libcamera.dox
>
> diff --git a/Documentation/Doxyfile.in b/Documentation/Doxyfile.in
> index a271c7bc..625d1e90 100644
> --- a/Documentation/Doxyfile.in
> +++ b/Documentation/Doxyfile.in
> @@ -53,6 +53,7 @@ EXCLUDE_SYMBOLS        = libcamera::BoundMethodArgs \
>
>  EXCLUDE_SYMLINKS       = YES
>
> +ENABLED_SECTIONS       = @ENABLED_SECTIONS@
>  HIDE_UNDOC_CLASSES     = @HIDE_UNDOC_CLASSES@
>  HIDE_UNDOC_MEMBERS     = @HIDE_UNDOC_MEMBERS@
>  HTML_OUTPUT            = @HTML_OUTPUT@
> diff --git a/Documentation/libcamera.dox b/Documentation/libcamera.dox
> new file mode 100644
> index 00000000..d5a57653
> --- /dev/null
> +++ b/Documentation/libcamera.dox
> @@ -0,0 +1,33 @@
> +/**
> +\mainpage libcamera API reference
> +
> +Welcome to the API reference for <a href="https://libcamera.org/">libcamera</a>,
> +a complex camera support library for Linux, Android and ChromeOS. These pages
> +are automatically generated from the libcamera source code and describe the API
> +in detail - if this is your first interaction with libcamera then you may find
> +it useful to visit the [developer's guide](../html/guides/introduction.html) in
> +the first instance, which can provide a more generic introduction to the
> +library's concepts.
> +
> +\if internal
> +
> +As a follow-on to the developer's guide, to assist you in adding support for
> +your platform the [pipeline handler writer's guide](../html/guides/pipeline-handler.html)
> +and the [ipa module writer's guide](../html/guides/ipa.html) should be helpful.
> +
> +The full libcamera API is documented here. If you wish to see only the public
> +part of the API you can use [these pages](../api-html/index.html) instead.
> +
> +\else
> +
> +As a follow-on to the developer's guide, to assist you in using libcamera within
> +your project the [application developer's guide](../html/guides/application-developer.html)
> +gives an overview on how to achieve that.
> +
> +Only the public part of the libcamera API is documented here; if you are a
> +developer seeking to add support for your hardware to the library or make other
> +improvements, you should switch to the internal API
> +[reference pages](../internal-api-html/index.html) instead.
> +
> +\endif
> +*/
> diff --git a/Documentation/meson.build b/Documentation/meson.build
> index afaad751..ab8168bb 100644
> --- a/Documentation/meson.build
> +++ b/Documentation/meson.build
> @@ -62,6 +62,7 @@ if doxygen.found() and dot.found()
>
>      cdata_public = configuration_data()
>      cdata_public.merge_from(cdata)
> +    cdata_public.set('ENABLED_SECTIONS', '')
>      cdata_public.set('HIDE_UNDOC_CLASSES', 'YES')
>      cdata_public.set('HIDE_UNDOC_MEMBERS', 'YES')
>      cdata_public.set('HTML_OUTPUT', 'api-html')
> @@ -89,6 +90,7 @@ if doxygen.found() and dot.found()
>
>      cdata_internal = configuration_data()
>      cdata_internal.merge_from(cdata)
> +    cdata_internal.set('ENABLED_SECTIONS', 'internal')
>      cdata_internal.set('HIDE_UNDOC_CLASSES', 'NO')
>      cdata_internal.set('HIDE_UNDOC_MEMBERS', 'NO')
>      cdata_internal.set('HTML_OUTPUT', 'internal-api-html')
> --
> 2.34.1
>