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

[Dan Scally]

On 09/01/2024 21:58, Kieran Bingham wrote:
> 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.
I'll rename to 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>


Thanks!

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