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

[Daniel Scally]

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>
---
This patch depends on "[PATCH 2/2] libcamera: Documentation: Split public/private documentation"

 Documentation/Doxyfile.in   |  6 ++++--
 Documentation/libcamera.dox | 33 +++++++++++++++++++++++++++++++++
 2 files changed, 37 insertions(+), 2 deletions(-)
 create mode 100644 Documentation/libcamera.dox

diff --git a/Documentation/Doxyfile.in b/Documentation/Doxyfile.in
index 6689ace1..1c6412ed 100644
--- a/Documentation/Doxyfile.in
+++ b/Documentation/Doxyfile.in
@@ -21,7 +21,8 @@ CASE_SENSE_NAMES       = YES
 
 QUIET                  = YES
 
-INPUT                  = "@TOP_SRCDIR@/include/libcamera" \
+INPUT                  = "@TOP_SRCDIR@/Documentation" \
+                         "@TOP_SRCDIR@/include/libcamera" \
                          "@TOP_SRCDIR@/src/ipa/ipu3" \
                          "@TOP_SRCDIR@/src/ipa/libipa" \
                          "@TOP_SRCDIR@/src/libcamera" \
@@ -30,7 +31,8 @@ INPUT                  = "@TOP_SRCDIR@/include/libcamera" \
 
 FILE_PATTERNS          = *.c \
                          *.cpp \
-                         *.h
+                         *.h \
+                         *.dox
 
 RECURSIVE              = YES
 
diff --git a/Documentation/libcamera.dox b/Documentation/libcamera.dox
new file mode 100644
index 00000000..c3101739
--- /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 do
+not explain how to use libcamera to consume data from camera sensors in your
+application, nor how to add support to the library for your hardware. There is
+documentation available to detail how to achieve those things in detail, which
+may be a better first contact with libcamera as a developer. As a starting
+point we recommend the [developer's guide](../html/guides/introduction.html).
+
+As a follow-on to the developer's guide, if you wish add support for a new
+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.
+Alternatively if you are an application developer seeking to use libcamera within
+your work the [application developer's guide](../html/guides/application-developer.html)
+gives an overview on how to achieve that.
+
+\if internal
+
+If you are an application developer seeking to use libcamera with your program
+then you may find it useful to use the [reduced version](../api-html/index.html)
+of the API reference pages instead, which excludes library objects if they are
+intended for internal use only.
+
+\else
+
+If you are a developer seeking to add support for your hardware to the library
+or make other improvements, you should switch to the more complete internal API
+[reference pages](../internal-api-html/index.html) instead
+
+\endif
+*/
-- 
2.34.1