[libcamera-devel,v2,5/5] libcamera: Documentation: Improve doxygen main page
diff mbox series

Message ID 20240105164104.78398-6-dan.scally@ideasonboard.com
State Superseded
Headers show
Series
  • Improve libcamera documentation
Related show

Commit Message

Dan Scally Jan. 5, 2024, 4:41 p.m. UTC 
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@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 +++++++++++++++++++++++++++++++++
 Documentation/meson.build   |  2 ++
 3 files changed, 36 insertions(+)
 create mode 100644 Documentation/libcamera.dox

Comments

Jacopo Mondi Jan. 9, 2024, 2:52 p.m. UTC | #1 
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@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@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
>
Dan Scally Jan. 9, 2024, 7:52 p.m. UTC | #2 
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@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

>
> The text looks good to me, thanks!
>
> Reviewed-by: Jacopo Mondi <jacopo.mondi@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
>>
Kieran Bingham Jan. 9, 2024, 9:58 p.m. UTC | #3 
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@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@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@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
> >>
Jacopo Mondi Jan. 10, 2024, 8:10 a.m. UTC | #4 
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@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@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
> > >
Dan Scally Jan. 12, 2024, 10:28 a.m. UTC | #5 
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@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@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@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
>>>>

Patch
diff mbox series 

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')