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

[Kieran Bingham]

Quoting Dan Scally via libcamera-devel (2024-01-09 19:52:17)
> Hi Jacopo
> 
> On 09/01/2024 14:52, Jacopo Mondi wrote:
> > 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..
> 
> 
> Honestly just the first thing that sprang to mind; naming things really isn't my strong suit! It can 
> be named whatever we want, it's the \mainpage tag within the file that sends it to the index.html in 
> doxygen's generated pages

I think we should probably call this main.dox or mainpage.dox then.

> 
> >
> > The text looks good to me, thanks!
> >
> > Reviewed-by: Jacopo Mondi <jacopo.mondi at ideasonboard.com>
> Thanks!
> >
> >>   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.

That's a nice way to split things.

We can probably expand on the main page later, but this looks like a
good starting point to me to get this split handled.

Reviewed-by: Kieran Bingham <kieran.bingham at ideasonboard.com>

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