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

[Jacopo Mondi]

HI Dan

On Tue, Jan 09, 2024 at 07:52:17PM +0000, Dan Scally wrote:
> 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 was not questioning the naming at all, I just wasn't sure how does
libcamera.dox get picked, and that's what \mainpage is for! Thanks for
the clarification

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