[v7,4/5] Documentation: Improve doxygen main page

20843 diff mbox series

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.

Reviewed-by: Jacopo Mondi <jacopo.mondi@ideasonboard.com>
Reviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
Signed-off-by: Daniel Scally <dan.scally@ideasonboard.com>
---
Changes since v6:

	- Addressed knock-on effect of patch #1 changes - no need to set the
	  ENABLED_SECTIONS in Doxyfiles anymore, as it was already done.

 Documentation/mainpage.dox | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)
 create mode 100644 Documentation/mainpage.dox

Hi Dan,

Thank you for the patch.

On Thu, Aug 08, 2024 at 03:09:47PM +0100, Daniel Scally 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.
> 
> Reviewed-by: Jacopo Mondi <jacopo.mondi@ideasonboard.com>
> Reviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
> Signed-off-by: Daniel Scally <dan.scally@ideasonboard.com>

Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>

> ---
> Changes since v6:
> 
> 	- Addressed knock-on effect of patch #1 changes - no need to set the
> 	  ENABLED_SECTIONS in Doxyfiles anymore, as it was already done.
> 
>  Documentation/mainpage.dox | 33 +++++++++++++++++++++++++++++++++
>  1 file changed, 33 insertions(+)
>  create mode 100644 Documentation/mainpage.dox
> 
> diff --git a/Documentation/mainpage.dox b/Documentation/mainpage.dox
> new file mode 100644
> index 00000000..d5a57653
> --- /dev/null
> +++ b/Documentation/mainpage.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
> +*/