[v2,6/7] Documentation: Expand introductory content on docs.rst
diff mbox series

Message ID 20240815082944.170109-7-dan.scally@ideasonboard.com
State Superseded
Headers show
Series
  • Documentation improvements
Related show

Commit Message

Dan Scally Aug. 15, 2024, 8:29 a.m. UTC 
docs.rst is the landing page for the documentation from the libcamera
website, but isn't particularly introductory. Move much of the content
from guides/introduction.rst to docs.rst, which will serve as the new
introductory page. Remove guides/introduction.rst.

Signed-off-by: Daniel Scally <dan.scally@ideasonboard.com>
---
Changes since v1:

	- Removed deleted file from meson's docs_sources array.

 Documentation/c55.svg                    | 175 +++++++++++++++++++++++
 Documentation/docs.rst                   | 128 ++++++++++++++++-
 Documentation/documentation-contents.rst |   1 -
 Documentation/guides/introduction.rst    |  78 ----------
 Documentation/index.rst                  |   1 -
 Documentation/meson.build                |   1 -
 6 files changed, 296 insertions(+), 88 deletions(-)
 create mode 100644 Documentation/c55.svg
 delete mode 100644 Documentation/guides/introduction.rst

Comments

Laurent Pinchart Aug. 18, 2024, 11:01 p.m. UTC | #1 
Hi Dan,

Thank you for the patch.

On Thu, Aug 15, 2024 at 09:29:43AM +0100, Daniel Scally wrote:
> docs.rst is the landing page for the documentation from the libcamera
> website, but isn't particularly introductory. Move much of the content
> from guides/introduction.rst to docs.rst, which will serve as the new
> introductory page. Remove guides/introduction.rst.
> 
> Signed-off-by: Daniel Scally <dan.scally@ideasonboard.com>
> ---
> Changes since v1:
> 
> 	- Removed deleted file from meson's docs_sources array.
> 
>  Documentation/c55.svg                    | 175 +++++++++++++++++++++++
>  Documentation/docs.rst                   | 128 ++++++++++++++++-
>  Documentation/documentation-contents.rst |   1 -
>  Documentation/guides/introduction.rst    |  78 ----------
>  Documentation/index.rst                  |   1 -
>  Documentation/meson.build                |   1 -
>  6 files changed, 296 insertions(+), 88 deletions(-)
>  create mode 100644 Documentation/c55.svg
>  delete mode 100644 Documentation/guides/introduction.rst
> 
> diff --git a/Documentation/c55.svg b/Documentation/c55.svg
> new file mode 100644
> index 00000000..9dbd52bb
> --- /dev/null
> +++ b/Documentation/c55.svg
> @@ -0,0 +1,175 @@
> +<?xml version="1.0" encoding="UTF-8" standalone="no"?>
> +<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
> + "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
> +<!-- Generated by graphviz version 2.43.0 (0)
> + -->

Sphinx has a graphviz extension. I've tested it locally and it works
quite nicely, with the following diff:

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 325f27591cfb..1f087c14e744 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -37,8 +37,11 @@ author = u'Kieran Bingham, Jacopo Mondi, Laurent Pinchart, Niklas Söderlund'
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    'sphinx.ext.graphviz',
 ]

+graphviz_output_format = 'svg'
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = []

diff --git a/Documentation/docs.rst b/Documentation/docs.rst
index c495fa61e40e..1cf2f4d6c744 100644
--- a/Documentation/docs.rst
+++ b/Documentation/docs.rst
@@ -58,7 +58,7 @@ desirable results from the camera through the kernel's APIs, reducing those
 operations to a simple and consistent method for developers. In short instead of
 having to deal with this:

-.. figure:: c55.svg
+.. graphviz:: mali-c55.dot

 You can instead simply deal with this::

diff --git a/Documentation/meson.build b/Documentation/meson.build
index 1c982ba6f862..c8433f33c0a4 100644
--- a/Documentation/meson.build
+++ b/Documentation/meson.build
@@ -139,6 +139,7 @@ if sphinx.found()
         'guides/tracing.rst',
         'index.rst',
         'lens_driver_requirements.rst',
+        'mali-c55.dot',
         'python-bindings.rst',
         'sensor_driver_requirements.rst',
         'software-isp-benchmarking.rst',

(and c55.svg replaced with mali-c55.dot).

Adding the .dot file to the docs_sources isn't a requirement specific to
.dot input files, the .svg should have been added there too.

The sphinx extension is part of the base sphinx package on Debian, so
using it should be fine.

[snip]

> diff --git a/Documentation/docs.rst b/Documentation/docs.rst
> index d65b2b4f..c495fa61 100644
> --- a/Documentation/docs.rst
> +++ b/Documentation/docs.rst
> @@ -14,12 +14,87 @@ Documentation
>  
>     API <api-html/index>
>  
> -API
> -===
> +What is libcamera exactly?

I would drop "exactly".

> +==========================
> +
> +libcamera is an open source complex camera support library for Linux. The

To match the Doxygen documentation, the README.rst file and the website,
you should write "for Linux, Android and ChromeOS".

> +library interfaces with Linux kernel uAPIs implemented by device drivers and

I'd write "with Linux kernel device drivers"

> +provides an intuitive API to developers in order to simplify the complexity
> +involved in capturing images from complex cameras on Linux systems.
> +
> +What's a "complex camera"?

"What is"

> +==========================
> +
> +A modern "camera" tends to infact be several different pieces of hardware which
> +must all be controlled together in order to capture images. For example the
> +pipeline might consist of a camera sensor which actually records the data, a
> +receiver which accepts those data transmitted from the camera sensor and an
> +image signal processor which processes those data into a useful image in an
> +accepted format.

I like the storyline here, but I think I would make this paragraph a bit
clearer:

A modern "camera" tends to infact be several different pieces of hardware which
must all be controlled together in order to produce and capture images of
appropriate quality. A hardware pipeline typically consists of a camera sensor
that captures raw frames and transmits them on a bus, a receiver that decodes
the bus signals, and an image signal processor that processes raw frames to
produce usable images in a standard format.

> The Linux kernel handles these multimedia devices through the
> +'Linux media' subsystem and provides a set of APIs (application programming

s/APIs (/

> +interfaces) known collectively as V4L2 (`Video for Linux 2`_) and the
> +`Media Controller`_ API which provide an interface to interact and control media

s/API/APIs/

(to avoid repeating "API").

> +devices.
> +
> +.. _Video for Linux 2: https://www.linuxtv.org/downloads/v4l-dvb-apis-new/userspace-api/v4l/v4l2.html
> +.. _Media Controller: https://www.linuxtv.org/downloads/v4l-dvb-apis-new/userspace-api/mediactl/media-controller.html
> +
> +Included in this subsystem are drivers for camera sensors, CSI2 (Camera
> +Serial Interface) receivers, and ISPs (Image Signal Processors)

s/$/./

> +
> +The usage of these drivers to provide a functioning camera stack is a
> +responsibility that lies in userspace which is commonly implemented separately
> +by vendors without a common architecture or API for application developers. This
> +adds a lot of complexity to the task, particularly when considering that the
> +differences in hardware pipelines and their representation in the kernel's APIs
> +often necessitates bespoke handling.

s/necessitates/necessitate/ if the subject is differences.

> +
> +What is libcamera for?
> +======================
>  
> -The libcamera API is extensively documented using Doxygen. The :ref:`API
> -nightly build <api>` contains the most up-to-date API documentation, built from
> -the latest master branch.
> +libcamera provides a complete camera stack for Linux based systems to abstract

s/Linux based/Linux-based/

> +the configuration of hardware and image control algorithms required to obtain
> +desirable results from the camera through the kernel's APIs, reducing those
> +operations to a simple and consistent method for developers. In short instead of
> +having to deal with this:
> +
> +.. figure:: c55.svg
> +
> +You can instead simply deal with this::
> +

Let's get syntax highlighting:

You can instead simply deal with this:

.. code-block:: python

> +  >>> import libcamera as lc
> +  >>> camera_manager = lc.CameraManager.singleton()
> +  [0:15:59.582029920] [504]  INFO Camera camera_manager.cpp:313 libcamera v0.3.0+182-01e57380
> +  >>> for camera in camera_manager.cameras:
> +  ...     print(f' - {camera.id}')
> +  ...
> +   - mali-c55 tpg
> +   - imx415 1-001a
> +
> +And the library handles the rest for you. These documentary pages give more
> +information on the internal workings of libcamera (and the kernel camera stack
> +that lies behind it) as well as guidance on using libcamera in an application or
> +extending the library with support for your hardware (through the pipeline
> +handler and IPA module writer's guides).
> +
> +How should I use it?
> +====================
> +
> +There are a few ways you might want to use libcamera, depending on your
> +application. It's always possible to use the library directly of course, and you
> +can find detailed information on how to do so in the
> +:doc:`application writer's guide <guides/application-developer>`. It may be more
> +appropriate to use one of the frameworks with libcamera support. For example an
> +application powering an embedded media device incorporating capture, encoding
> +and streaming of both video and audio might benefit from using `gstreamer`_ (for

s/gstreamer/GStreamer/
s/ (/, /

> +which libcamera provides a plugin). Similarly an application for user-facing

s/)//

> +devices like a laptop would likely benefit accessing cameras through the XDG
> +camera portal and `pipewire`_, which brings the advantages of resource sharing
> +(multiple applications accessing the stream at the same time) and access
> +control.

Should you mention the Android camera HAL and V4L2 compatibility layer
here ?

> +
> +.. _gstreamer: https://gstreamer.freedesktop.org/
> +.. _pipewire: https://pipewire.org/

So far I think it's a nice introduction, but I believe the rest belongs
to a different page. Actually it depends on what audience we target the
main page for. The two main options I can think of are libcamera users
(I put applications developers and system integrators in this category
for now), and libcamera developers. I'm leaning towards the former, in
which case I think it would make sense to move the contents of the
camera_stack.rst page here, and move the internal architecture to a separate
page.

>  
>  libcamera Architecture
>  ======================
> @@ -177,7 +252,7 @@ Helpers and Support Classes
>  
>  
>  V4L2 Compatibility Layer
> -------------------------
> +========================
>  
>  V4L2 compatibility is achieved through a shared library that traps all
>  accesses to camera devices and routes them to libcamera to emulate high-level
> @@ -190,7 +265,7 @@ designed for video conferencing.
>  
>  
>  Android Camera HAL
> -------------------
> +==================
>  
>  Camera support for Android is achieved through a generic Android
>  camera HAL implementation on top of libcamera. The HAL will implement internally
> @@ -200,3 +275,42 @@ support.
>  The Android camera HAL implementation will initially target the
>  LIMITED hardware level, with support for the FULL level then being gradually
>  implemented.


The description of the compat layers duplicates the text in
camera_stack.rst. Moving the whole stack description here will fix that.

> +
> +Platform Support
> +================
> +
> +The library currently supports the following hardware platforms specifically
> +with dedicated pipeline handlers:
> +
> +   -  Arm Mali-C55 (mali-c55)

I think you can use a single space after the '-'.

> +   -  Intel IPU3 (ipu3)

   -  NXP i.MX8MP (imx8-isi and rkisp1)

> +   -  Rockchip RK3399 (rkisp1)
> +   -  RaspberryPi 3 and 4 (rpi/vc4)

   - Raspberry Pi 3, 4 and zero (rpi/vc4)

> +
> +Furthermore, generic platform support is provided for the following:
> +
> +   -  USB video device class cameras (uvcvideo)
> +   -  iMX7, Allwinner Sun6i (simple)

IPU6 works too. There are also other platforms supported by the simple
pipeline handler.

If we move the architecture to a separate document, there will be no
mention of pipeline handlers here anymore. This text could be reworked
to list platforms from a user point of view, maybe based on the level of
support they have (with ISP, with software ISP, without ISP, ...).

You're mainly moving contents here, so this could be done in a separate
patch.

> +   -  Virtual media controller driver for test use cases (vimc)
> +
> +Licensing
> +=========
> +
> +The libcamera core, is covered by the `LGPL-2.1-or-later`_ license. Pipeline
> +Handlers are a part of the libcamera code base and need to be contributed
> +upstream by device vendors. IPA modules included in libcamera are covered by a
> +free software license, however third-parties may develop IPA modules outside of
> +libcamera and distribute them under a closed-source license, provided they do
> +not include source code from the libcamera project.
> +
> +The libcamera project itself contains multiple libraries, applications and
> +utilities. Licenses are expressed through SPDX tags in text-based files that
> +support comments, and through the .reuse/dep5 file otherwise. A copy of all
> +licenses are stored in the LICENSES directory, and a full summary of the
> +licensing used throughout the project can be found in the COPYING.rst document.
> +
> +Applications which link dynamically against libcamera and use only the public
> +API are an independent work of the authors and have no license restrictions
> +imposed upon them from libcamera.
> +
> +.. _LGPL-2.1-or-later: https://spdx.org/licenses/LGPL-2.1-or-later.html

This section feels a bit out-of-place, but I don't have a better
suggestion for now.

> diff --git a/Documentation/documentation-contents.rst b/Documentation/documentation-contents.rst
> index 613366d1..d978b704 100644
> --- a/Documentation/documentation-contents.rst
> +++ b/Documentation/documentation-contents.rst
> @@ -10,7 +10,6 @@
>     * :doc:`/environment_variables`
>     * :doc:`/feature_requirements`
>     * :doc:`/guides/application-developer`
> -   * :doc:`/guides/introduction`

I would also rename docs.rst to introduction.rst now that it has become
an introduction.

>     * :doc:`/guides/ipa`
>     * :doc:`/guides/pipeline-handler`
>     * :doc:`/guides/tracing`
> diff --git a/Documentation/guides/introduction.rst b/Documentation/guides/introduction.rst
> deleted file mode 100644
> index e419eb9d..00000000
> --- a/Documentation/guides/introduction.rst
> +++ /dev/null
> @@ -1,78 +0,0 @@
> -.. SPDX-License-Identifier: CC-BY-SA-4.0
> -
> -.. include:: ../documentation-contents.rst
> -
> -Developers guide to libcamera
> -=============================
> -
> -The Linux kernel handles multimedia devices through the 'Linux media' subsystem
> -and provides a set of APIs (application programming interfaces) known
> -collectively as V4L2 (`Video for Linux 2`_) and the `Media Controller`_ API
> -which provide an interface to interact and control media devices.
> -
> -Included in this subsystem are drivers for camera sensors, CSI2 (Camera
> -Serial Interface) receivers, and ISPs (Image Signal Processors)
> -
> -The usage of these drivers to provide a functioning camera stack is a
> -responsibility that lies in userspace which is commonly implemented separately
> -by vendors without a common architecture or API for application developers.
> -
> -libcamera provides a complete camera stack for Linux based systems to abstract
> -functionality desired by camera application developers and process the
> -configuration of hardware and image control algorithms required to obtain
> -desirable results from the camera.
> -
> -.. _Video for Linux 2: https://www.linuxtv.org/downloads/v4l-dvb-apis-new/userspace-api/v4l/v4l2.html
> -.. _Media Controller: https://www.linuxtv.org/downloads/v4l-dvb-apis-new/userspace-api/mediactl/media-controller.html
> -
> -
> -In this developers guide the current `Platform Support`_ is detailed, as well as
> -an overview of the `Licensing`_ requirements of the project.
> -
> -This introduction is followed by a walkthrough tutorial to newcomers wishing to
> -support a new platform with the `Pipeline Handler Writers Guide`_ and for those
> -looking to make use of the libcamera native API an `Application Writers Guide`_
> -provides a tutorial of the key APIs exposed by libcamera.
> -
> -.. _Pipeline Handler Writers Guide: pipeline-handler.html
> -.. _Application Writers Guide: application-developer.html
> -
> -.. TODO: Correctly link to the other articles of the guide
> -
> -Platform Support
> -----------------
> -
> -The library currently supports the following hardware platforms specifically
> -with dedicated pipeline handlers:
> -
> -   -  Intel IPU3 (ipu3)
> -   -  Rockchip RK3399 (rkisp1)
> -   -  RaspberryPi 3 and 4 (rpi/vc4)
> -
> -Furthermore, generic platform support is provided for the following:
> -
> -   -  USB video device class cameras (uvcvideo)
> -   -  iMX7, Allwinner Sun6i (simple)
> -   -  Virtual media controller driver for test use cases (vimc)
> -
> -Licensing
> ----------
> -
> -The libcamera core, is covered by the `LGPL-2.1-or-later`_ license. Pipeline
> -Handlers are a part of the libcamera code base and need to be contributed
> -upstream by device vendors. IPA modules included in libcamera are covered by a
> -free software license, however third-parties may develop IPA modules outside of
> -libcamera and distribute them under a closed-source license, provided they do
> -not include source code from the libcamera project.
> -
> -The libcamera project itself contains multiple libraries, applications and
> -utilities. Licenses are expressed through SPDX tags in text-based files that
> -support comments, and through the .reuse/dep5 file otherwise. A copy of all
> -licenses are stored in the LICENSES directory, and a full summary of the
> -licensing used throughout the project can be found in the COPYING.rst document.
> -
> -Applications which link dynamically against libcamera and use only the public
> -API are an independent work of the authors and have no license restrictions
> -imposed upon them from libcamera.
> -
> -.. _LGPL-2.1-or-later: https://spdx.org/licenses/LGPL-2.1-or-later.html
> diff --git a/Documentation/index.rst b/Documentation/index.rst
> index 59416906..6d7d2ca3 100644
> --- a/Documentation/index.rst
> +++ b/Documentation/index.rst
> @@ -17,7 +17,6 @@
>     Application Writer's Guide <guides/application-developer>
>     Camera Sensor Model <camera-sensor-model>
>     Camera Stack <camera_stack>
> -   Developer Guide <guides/introduction>
>     Environment variables <environment_variables>
>     Feature Requirements <feature_requirements>
>     IPA Writer's guide <guides/ipa>
> diff --git a/Documentation/meson.build b/Documentation/meson.build
> index 74cffc11..32642f32 100644
> --- a/Documentation/meson.build
> +++ b/Documentation/meson.build
> @@ -134,7 +134,6 @@ if sphinx.found()
>          'environment_variables.rst',
>  	'feature_requirements.rst','
>          'guides/application-developer.rst',
> -        'guides/introduction.rst',
>          'guides/ipa.rst',
>          'guides/pipeline-handler.rst',
>          'guides/tracing.rst',

Patch
diff mbox series 

diff --git a/Documentation/c55.svg b/Documentation/c55.svg
new file mode 100644
index 00000000..9dbd52bb
--- /dev/null
+++ b/Documentation/c55.svg
@@ -0,0 +1,175 @@ 
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
+ "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<!-- Generated by graphviz version 2.43.0 (0)
+ -->
+<!-- Title: board Pages: 1 -->
+<svg width="484pt" height="530pt"
+ viewBox="0.00 0.00 483.50 530.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 526)">
+<title>board</title>
+<polygon fill="white" stroke="transparent" points="-4,4 -4,-526 479.5,-526 479.5,4 -4,4"/>
+<!-- n00000001 -->
+<g id="node1" class="node">
+<title>n00000001</title>
+<path fill="green" stroke="black" d="M20.5,-316.5C20.5,-316.5 133.5,-316.5 133.5,-316.5 139.5,-316.5 145.5,-322.5 145.5,-328.5 145.5,-328.5 145.5,-388.5 145.5,-388.5 145.5,-394.5 139.5,-400.5 133.5,-400.5 133.5,-400.5 20.5,-400.5 20.5,-400.5 14.5,-400.5 8.5,-394.5 8.5,-388.5 8.5,-388.5 8.5,-328.5 8.5,-328.5 8.5,-322.5 14.5,-316.5 20.5,-316.5"/>
+<text text-anchor="middle" x="77" y="-385.3" font-family="Times,serif" font-size="14.00"> </text>
+<polyline fill="none" stroke="black" points="8.5,-377.5 145.5,-377.5 "/>
+<text text-anchor="middle" x="77" y="-362.3" font-family="Times,serif" font-size="14.00">mali&#45;c55 tpg</text>
+<text text-anchor="middle" x="77" y="-347.3" font-family="Times,serif" font-size="14.00">/dev/v4l&#45;subdev0</text>
+<polyline fill="none" stroke="black" points="8.5,-339.5 145.5,-339.5 "/>
+<text text-anchor="middle" x="77" y="-324.3" font-family="Times,serif" font-size="14.00">0</text>
+</g>
+<!-- n00000003 -->
+<g id="node2" class="node">
+<title>n00000003</title>
+<path fill="green" stroke="black" d="M210.5,-195.5C210.5,-195.5 323.5,-195.5 323.5,-195.5 329.5,-195.5 335.5,-201.5 335.5,-207.5 335.5,-207.5 335.5,-267.5 335.5,-267.5 335.5,-273.5 329.5,-279.5 323.5,-279.5 323.5,-279.5 210.5,-279.5 210.5,-279.5 204.5,-279.5 198.5,-273.5 198.5,-267.5 198.5,-267.5 198.5,-207.5 198.5,-207.5 198.5,-201.5 204.5,-195.5 210.5,-195.5"/>
+<text text-anchor="middle" x="232.5" y="-264.3" font-family="Times,serif" font-size="14.00">0</text>
+<polyline fill="none" stroke="black" points="266.5,-256.5 266.5,-279.5 "/>
+<text text-anchor="middle" x="301" y="-264.3" font-family="Times,serif" font-size="14.00">4</text>
+<polyline fill="none" stroke="black" points="198.5,-256.5 335.5,-256.5 "/>
+<text text-anchor="middle" x="267" y="-241.3" font-family="Times,serif" font-size="14.00">mali&#45;c55 isp</text>
+<text text-anchor="middle" x="267" y="-226.3" font-family="Times,serif" font-size="14.00">/dev/v4l&#45;subdev1</text>
+<polyline fill="none" stroke="black" points="198.5,-218.5 335.5,-218.5 "/>
+<text text-anchor="middle" x="221" y="-203.3" font-family="Times,serif" font-size="14.00">1</text>
+<polyline fill="none" stroke="black" points="243.5,-195.5 243.5,-218.5 "/>
+<text text-anchor="middle" x="266.5" y="-203.3" font-family="Times,serif" font-size="14.00">2</text>
+<polyline fill="none" stroke="black" points="289.5,-195.5 289.5,-218.5 "/>
+<text text-anchor="middle" x="312.5" y="-203.3" font-family="Times,serif" font-size="14.00">3</text>
+</g>
+<!-- n00000001&#45;&gt;n00000003 -->
+<g id="edge1" class="edge">
+<title>n00000001:port0&#45;&gt;n00000003:port0</title>
+<path fill="none" stroke="black" stroke-dasharray="5,2" d="M147,-327.5C153.23,-327.5 151.15,-320.9 155,-316 169.96,-296.96 169.41,-275.56 186.85,-269.92"/>
+<polygon fill="black" stroke="black" points="187.58,-273.36 197,-268.5 186.61,-266.42 187.58,-273.36"/>
+</g>
+<!-- n00000009 -->
+<g id="node3" class="node">
+<title>n00000009</title>
+<path fill="green" stroke="black" d="M182,-74.5C182,-74.5 306,-74.5 306,-74.5 312,-74.5 318,-80.5 318,-86.5 318,-86.5 318,-146.5 318,-146.5 318,-152.5 312,-158.5 306,-158.5 306,-158.5 182,-158.5 182,-158.5 176,-158.5 170,-152.5 170,-146.5 170,-146.5 170,-86.5 170,-86.5 170,-80.5 176,-74.5 182,-74.5"/>
+<text text-anchor="middle" x="207" y="-143.3" font-family="Times,serif" font-size="14.00">0</text>
+<polyline fill="none" stroke="black" points="244,-135.5 244,-158.5 "/>
+<text text-anchor="middle" x="281" y="-143.3" font-family="Times,serif" font-size="14.00">2</text>
+<polyline fill="none" stroke="black" points="170,-135.5 318,-135.5 "/>
+<text text-anchor="middle" x="244" y="-120.3" font-family="Times,serif" font-size="14.00">mali&#45;c55 resizer fr</text>
+<text text-anchor="middle" x="244" y="-105.3" font-family="Times,serif" font-size="14.00">/dev/v4l&#45;subdev2</text>
+<polyline fill="none" stroke="black" points="170,-97.5 318,-97.5 "/>
+<text text-anchor="middle" x="244" y="-82.3" font-family="Times,serif" font-size="14.00">1</text>
+</g>
+<!-- n00000003&#45;&gt;n00000009 -->
+<g id="edge2" class="edge">
+<title>n00000003:port1&#45;&gt;n00000009:port0</title>
+<path fill="none" stroke="black" stroke-width="2" d="M221,-195C221,-181.86 212.79,-177.8 208.95,-168.92"/>
+<polygon fill="black" stroke="black" stroke-width="2" points="212.36,-168.14 207,-159 205.49,-169.49 212.36,-168.14"/>
+</g>
+<!-- n00000003&#45;&gt;n00000009 -->
+<g id="edge3" class="edge">
+<title>n00000003:port2&#45;&gt;n00000009:port2</title>
+<path fill="none" stroke="black" stroke-width="2" d="M266,-195C266,-181.73 274.79,-177.84 278.91,-168.96"/>
+<polygon fill="black" stroke="black" stroke-width="2" points="282.38,-169.51 281,-159 275.53,-168.07 282.38,-169.51"/>
+</g>
+<!-- n0000000d -->
+<g id="node4" class="node">
+<title>n0000000d</title>
+<path fill="green" stroke="black" d="M12,-74.5C12,-74.5 140,-74.5 140,-74.5 146,-74.5 152,-80.5 152,-86.5 152,-86.5 152,-146.5 152,-146.5 152,-152.5 146,-158.5 140,-158.5 140,-158.5 12,-158.5 12,-158.5 6,-158.5 0,-152.5 0,-146.5 0,-146.5 0,-86.5 0,-86.5 0,-80.5 6,-74.5 12,-74.5"/>
+<text text-anchor="middle" x="76" y="-143.3" font-family="Times,serif" font-size="14.00">0</text>
+<polyline fill="none" stroke="black" points="0,-135.5 152,-135.5 "/>
+<text text-anchor="middle" x="76" y="-120.3" font-family="Times,serif" font-size="14.00">mali&#45;c55 resizer ds</text>
+<text text-anchor="middle" x="76" y="-105.3" font-family="Times,serif" font-size="14.00">/dev/v4l&#45;subdev3</text>
+<polyline fill="none" stroke="black" points="0,-97.5 152,-97.5 "/>
+<text text-anchor="middle" x="76" y="-82.3" font-family="Times,serif" font-size="14.00">1</text>
+</g>
+<!-- n00000003&#45;&gt;n0000000d -->
+<g id="edge4" class="edge">
+<title>n00000003:port1&#45;&gt;n0000000d:port0</title>
+<path fill="none" stroke="black" stroke-width="2" d="M197,-206.5C170.51,-206.5 176.57,-180.43 161,-159 160.2,-157.9 159.66,-156.73 159.25,-155.57"/>
+<polygon fill="black" stroke="black" stroke-width="2" points="161.89,-153.26 153,-147.5 156.36,-157.55 161.89,-153.26"/>
+</g>
+<!-- n0000001c -->
+<g id="node5" class="node">
+<title>n0000001c</title>
+<polygon fill="yellow" stroke="black" points="475.5,-135.5 336.5,-135.5 336.5,-97.5 475.5,-97.5 475.5,-135.5"/>
+<text text-anchor="middle" x="406" y="-120.3" font-family="Times,serif" font-size="14.00">mali&#45;c55 3a stats</text>
+<text text-anchor="middle" x="406" y="-105.3" font-family="Times,serif" font-size="14.00">/dev/video3</text>
+</g>
+<!-- n00000003&#45;&gt;n0000001c -->
+<g id="edge5" class="edge">
+<title>n00000003:port3&#45;&gt;n0000001c</title>
+<path fill="none" stroke="black" d="M337,-206.5C368.55,-206.5 387.74,-171.13 397.62,-144.99"/>
+<polygon fill="black" stroke="black" points="400.94,-146.11 400.96,-135.51 394.33,-143.78 400.94,-146.11"/>
+</g>
+<!-- n00000010 -->
+<g id="node6" class="node">
+<title>n00000010</title>
+<polygon fill="yellow" stroke="black" points="293,-38 195,-38 195,0 293,0 293,-38"/>
+<text text-anchor="middle" x="244" y="-22.8" font-family="Times,serif" font-size="14.00">mali&#45;c55 fr</text>
+<text text-anchor="middle" x="244" y="-7.8" font-family="Times,serif" font-size="14.00">/dev/video0</text>
+</g>
+<!-- n00000009&#45;&gt;n00000010 -->
+<g id="edge6" class="edge">
+<title>n00000009:port1&#45;&gt;n00000010</title>
+<path fill="none" stroke="black" d="M244,-74C244,-65.79 244,-56.87 244,-48.69"/>
+<polygon fill="black" stroke="black" points="247.5,-48.49 244,-38.49 240.5,-48.49 247.5,-48.49"/>
+</g>
+<!-- n00000014 -->
+<g id="node7" class="node">
+<title>n00000014</title>
+<polygon fill="yellow" stroke="black" points="125,-38 27,-38 27,0 125,0 125,-38"/>
+<text text-anchor="middle" x="76" y="-22.8" font-family="Times,serif" font-size="14.00">mali&#45;c55 ds</text>
+<text text-anchor="middle" x="76" y="-7.8" font-family="Times,serif" font-size="14.00">/dev/video1</text>
+</g>
+<!-- n0000000d&#45;&gt;n00000014 -->
+<g id="edge7" class="edge">
+<title>n0000000d:port1&#45;&gt;n00000014</title>
+<path fill="none" stroke="black" d="M76,-74C76,-65.79 76,-56.87 76,-48.69"/>
+<polygon fill="black" stroke="black" points="79.5,-48.49 76,-38.49 72.5,-48.49 79.5,-48.49"/>
+</g>
+<!-- n00000018 -->
+<g id="node8" class="node">
+<title>n00000018</title>
+<polygon fill="yellow" stroke="black" points="475.5,-377.5 318.5,-377.5 318.5,-339.5 475.5,-339.5 475.5,-377.5"/>
+<text text-anchor="middle" x="397" y="-362.3" font-family="Times,serif" font-size="14.00">mali&#45;c55 3a params</text>
+<text text-anchor="middle" x="397" y="-347.3" font-family="Times,serif" font-size="14.00">/dev/video2</text>
+</g>
+<!-- n00000018&#45;&gt;n00000003 -->
+<g id="edge8" class="edge">
+<title>n00000018&#45;&gt;n00000003:port4</title>
+<path fill="none" stroke="black" d="M393.36,-339.49C387.61,-316.23 374.19,-277.78 347.14,-269.93"/>
+<polygon fill="black" stroke="black" points="347.39,-266.43 337,-268.5 346.42,-273.36 347.39,-266.43"/>
+</g>
+<!-- n00000030 -->
+<g id="node9" class="node">
+<title>n00000030</title>
+<path fill="green" stroke="black" d="M175.5,-316.5C175.5,-316.5 288.5,-316.5 288.5,-316.5 294.5,-316.5 300.5,-322.5 300.5,-328.5 300.5,-328.5 300.5,-388.5 300.5,-388.5 300.5,-394.5 294.5,-400.5 288.5,-400.5 288.5,-400.5 175.5,-400.5 175.5,-400.5 169.5,-400.5 163.5,-394.5 163.5,-388.5 163.5,-388.5 163.5,-328.5 163.5,-328.5 163.5,-322.5 169.5,-316.5 175.5,-316.5"/>
+<text text-anchor="middle" x="232" y="-385.3" font-family="Times,serif" font-size="14.00">0</text>
+<polyline fill="none" stroke="black" points="163.5,-377.5 300.5,-377.5 "/>
+<text text-anchor="middle" x="232" y="-362.3" font-family="Times,serif" font-size="14.00">lte&#45;csi2&#45;rx</text>
+<text text-anchor="middle" x="232" y="-347.3" font-family="Times,serif" font-size="14.00">/dev/v4l&#45;subdev4</text>
+<polyline fill="none" stroke="black" points="163.5,-339.5 300.5,-339.5 "/>
+<text text-anchor="middle" x="232" y="-324.3" font-family="Times,serif" font-size="14.00">1</text>
+</g>
+<!-- n00000030&#45;&gt;n00000003 -->
+<g id="edge9" class="edge">
+<title>n00000030:port1&#45;&gt;n00000003:port0</title>
+<path fill="none" stroke="black" d="M232,-316C232,-304 232,-298.75 232,-290.12"/>
+<polygon fill="black" stroke="black" points="235.5,-290 232,-280 228.5,-290 235.5,-290"/>
+</g>
+<!-- n00000035 -->
+<g id="node10" class="node">
+<title>n00000035</title>
+<path fill="green" stroke="black" d="M175.5,-437.5C175.5,-437.5 288.5,-437.5 288.5,-437.5 294.5,-437.5 300.5,-443.5 300.5,-449.5 300.5,-449.5 300.5,-509.5 300.5,-509.5 300.5,-515.5 294.5,-521.5 288.5,-521.5 288.5,-521.5 175.5,-521.5 175.5,-521.5 169.5,-521.5 163.5,-515.5 163.5,-509.5 163.5,-509.5 163.5,-449.5 163.5,-449.5 163.5,-443.5 169.5,-437.5 175.5,-437.5"/>
+<text text-anchor="middle" x="232" y="-506.3" font-family="Times,serif" font-size="14.00"> </text>
+<polyline fill="none" stroke="black" points="163.5,-498.5 300.5,-498.5 "/>
+<text text-anchor="middle" x="232" y="-483.3" font-family="Times,serif" font-size="14.00">imx415 1&#45;001a</text>
+<text text-anchor="middle" x="232" y="-468.3" font-family="Times,serif" font-size="14.00">/dev/v4l&#45;subdev5</text>
+<polyline fill="none" stroke="black" points="163.5,-460.5 300.5,-460.5 "/>
+<text text-anchor="middle" x="232" y="-445.3" font-family="Times,serif" font-size="14.00">0</text>
+</g>
+<!-- n00000035&#45;&gt;n00000030 -->
+<g id="edge10" class="edge">
+<title>n00000035:port0&#45;&gt;n00000030:port0</title>
+<path fill="none" stroke="black" stroke-width="2" d="M232,-437C232,-425 232,-419.75 232,-411.12"/>
+<polygon fill="black" stroke="black" stroke-width="2" points="235.5,-411 232,-401 228.5,-411 235.5,-411"/>
+</g>
+</g>
+</svg>
diff --git a/Documentation/docs.rst b/Documentation/docs.rst
index d65b2b4f..c495fa61 100644
--- a/Documentation/docs.rst
+++ b/Documentation/docs.rst
@@ -14,12 +14,87 @@  Documentation
 
    API <api-html/index>
 
-API
-===
+What is libcamera exactly?
+==========================
+
+libcamera is an open source complex camera support library for Linux. The
+library interfaces with Linux kernel uAPIs implemented by device drivers and
+provides an intuitive API to developers in order to simplify the complexity
+involved in capturing images from complex cameras on Linux systems.
+
+What's a "complex camera"?
+==========================
+
+A modern "camera" tends to infact be several different pieces of hardware which
+must all be controlled together in order to capture images. For example the
+pipeline might consist of a camera sensor which actually records the data, a
+receiver which accepts those data transmitted from the camera sensor and an
+image signal processor which processes those data into a useful image in an
+accepted format. The Linux kernel handles these multimedia devices through the
+'Linux media' subsystem and provides a set of APIs (application programming
+interfaces) known collectively as V4L2 (`Video for Linux 2`_) and the
+`Media Controller`_ API which provide an interface to interact and control media
+devices.
+
+.. _Video for Linux 2: https://www.linuxtv.org/downloads/v4l-dvb-apis-new/userspace-api/v4l/v4l2.html
+.. _Media Controller: https://www.linuxtv.org/downloads/v4l-dvb-apis-new/userspace-api/mediactl/media-controller.html
+
+Included in this subsystem are drivers for camera sensors, CSI2 (Camera
+Serial Interface) receivers, and ISPs (Image Signal Processors)
+
+The usage of these drivers to provide a functioning camera stack is a
+responsibility that lies in userspace which is commonly implemented separately
+by vendors without a common architecture or API for application developers. This
+adds a lot of complexity to the task, particularly when considering that the
+differences in hardware pipelines and their representation in the kernel's APIs
+often necessitates bespoke handling.
+
+What is libcamera for?
+======================
 
-The libcamera API is extensively documented using Doxygen. The :ref:`API
-nightly build <api>` contains the most up-to-date API documentation, built from
-the latest master branch.
+libcamera provides a complete camera stack for Linux based systems to abstract
+the configuration of hardware and image control algorithms required to obtain
+desirable results from the camera through the kernel's APIs, reducing those
+operations to a simple and consistent method for developers. In short instead of
+having to deal with this:
+
+.. figure:: c55.svg
+
+You can instead simply deal with this::
+
+  >>> import libcamera as lc
+  >>> camera_manager = lc.CameraManager.singleton()
+  [0:15:59.582029920] [504]  INFO Camera camera_manager.cpp:313 libcamera v0.3.0+182-01e57380
+  >>> for camera in camera_manager.cameras:
+  ...     print(f' - {camera.id}')
+  ...
+   - mali-c55 tpg
+   - imx415 1-001a
+
+And the library handles the rest for you. These documentary pages give more
+information on the internal workings of libcamera (and the kernel camera stack
+that lies behind it) as well as guidance on using libcamera in an application or
+extending the library with support for your hardware (through the pipeline
+handler and IPA module writer's guides).
+
+How should I use it?
+====================
+
+There are a few ways you might want to use libcamera, depending on your
+application. It's always possible to use the library directly of course, and you
+can find detailed information on how to do so in the
+:doc:`application writer's guide <guides/application-developer>`. It may be more
+appropriate to use one of the frameworks with libcamera support. For example an
+application powering an embedded media device incorporating capture, encoding
+and streaming of both video and audio might benefit from using `gstreamer`_ (for
+which libcamera provides a plugin). Similarly an application for user-facing
+devices like a laptop would likely benefit accessing cameras through the XDG
+camera portal and `pipewire`_, which brings the advantages of resource sharing
+(multiple applications accessing the stream at the same time) and access
+control.
+
+.. _gstreamer: https://gstreamer.freedesktop.org/
+.. _pipewire: https://pipewire.org/
 
 libcamera Architecture
 ======================
@@ -177,7 +252,7 @@  Helpers and Support Classes
 
 
 V4L2 Compatibility Layer
-------------------------
+========================
 
 V4L2 compatibility is achieved through a shared library that traps all
 accesses to camera devices and routes them to libcamera to emulate high-level
@@ -190,7 +265,7 @@  designed for video conferencing.
 
 
 Android Camera HAL
-------------------
+==================
 
 Camera support for Android is achieved through a generic Android
 camera HAL implementation on top of libcamera. The HAL will implement internally
@@ -200,3 +275,42 @@  support.
 The Android camera HAL implementation will initially target the
 LIMITED hardware level, with support for the FULL level then being gradually
 implemented.
+
+Platform Support
+================
+
+The library currently supports the following hardware platforms specifically
+with dedicated pipeline handlers:
+
+   -  Arm Mali-C55 (mali-c55)
+   -  Intel IPU3 (ipu3)
+   -  Rockchip RK3399 (rkisp1)
+   -  RaspberryPi 3 and 4 (rpi/vc4)
+
+Furthermore, generic platform support is provided for the following:
+
+   -  USB video device class cameras (uvcvideo)
+   -  iMX7, Allwinner Sun6i (simple)
+   -  Virtual media controller driver for test use cases (vimc)
+
+Licensing
+=========
+
+The libcamera core, is covered by the `LGPL-2.1-or-later`_ license. Pipeline
+Handlers are a part of the libcamera code base and need to be contributed
+upstream by device vendors. IPA modules included in libcamera are covered by a
+free software license, however third-parties may develop IPA modules outside of
+libcamera and distribute them under a closed-source license, provided they do
+not include source code from the libcamera project.
+
+The libcamera project itself contains multiple libraries, applications and
+utilities. Licenses are expressed through SPDX tags in text-based files that
+support comments, and through the .reuse/dep5 file otherwise. A copy of all
+licenses are stored in the LICENSES directory, and a full summary of the
+licensing used throughout the project can be found in the COPYING.rst document.
+
+Applications which link dynamically against libcamera and use only the public
+API are an independent work of the authors and have no license restrictions
+imposed upon them from libcamera.
+
+.. _LGPL-2.1-or-later: https://spdx.org/licenses/LGPL-2.1-or-later.html
diff --git a/Documentation/documentation-contents.rst b/Documentation/documentation-contents.rst
index 613366d1..d978b704 100644
--- a/Documentation/documentation-contents.rst
+++ b/Documentation/documentation-contents.rst
@@ -10,7 +10,6 @@ 
    * :doc:`/environment_variables`
    * :doc:`/feature_requirements`
    * :doc:`/guides/application-developer`
-   * :doc:`/guides/introduction`
    * :doc:`/guides/ipa`
    * :doc:`/guides/pipeline-handler`
    * :doc:`/guides/tracing`
diff --git a/Documentation/guides/introduction.rst b/Documentation/guides/introduction.rst
deleted file mode 100644
index e419eb9d..00000000
--- a/Documentation/guides/introduction.rst
+++ /dev/null
@@ -1,78 +0,0 @@ 
-.. SPDX-License-Identifier: CC-BY-SA-4.0
-
-.. include:: ../documentation-contents.rst
-
-Developers guide to libcamera
-=============================
-
-The Linux kernel handles multimedia devices through the 'Linux media' subsystem
-and provides a set of APIs (application programming interfaces) known
-collectively as V4L2 (`Video for Linux 2`_) and the `Media Controller`_ API
-which provide an interface to interact and control media devices.
-
-Included in this subsystem are drivers for camera sensors, CSI2 (Camera
-Serial Interface) receivers, and ISPs (Image Signal Processors)
-
-The usage of these drivers to provide a functioning camera stack is a
-responsibility that lies in userspace which is commonly implemented separately
-by vendors without a common architecture or API for application developers.
-
-libcamera provides a complete camera stack for Linux based systems to abstract
-functionality desired by camera application developers and process the
-configuration of hardware and image control algorithms required to obtain
-desirable results from the camera.
-
-.. _Video for Linux 2: https://www.linuxtv.org/downloads/v4l-dvb-apis-new/userspace-api/v4l/v4l2.html
-.. _Media Controller: https://www.linuxtv.org/downloads/v4l-dvb-apis-new/userspace-api/mediactl/media-controller.html
-
-
-In this developers guide the current `Platform Support`_ is detailed, as well as
-an overview of the `Licensing`_ requirements of the project.
-
-This introduction is followed by a walkthrough tutorial to newcomers wishing to
-support a new platform with the `Pipeline Handler Writers Guide`_ and for those
-looking to make use of the libcamera native API an `Application Writers Guide`_
-provides a tutorial of the key APIs exposed by libcamera.
-
-.. _Pipeline Handler Writers Guide: pipeline-handler.html
-.. _Application Writers Guide: application-developer.html
-
-.. TODO: Correctly link to the other articles of the guide
-
-Platform Support
-----------------
-
-The library currently supports the following hardware platforms specifically
-with dedicated pipeline handlers:
-
-   -  Intel IPU3 (ipu3)
-   -  Rockchip RK3399 (rkisp1)
-   -  RaspberryPi 3 and 4 (rpi/vc4)
-
-Furthermore, generic platform support is provided for the following:
-
-   -  USB video device class cameras (uvcvideo)
-   -  iMX7, Allwinner Sun6i (simple)
-   -  Virtual media controller driver for test use cases (vimc)
-
-Licensing
----------
-
-The libcamera core, is covered by the `LGPL-2.1-or-later`_ license. Pipeline
-Handlers are a part of the libcamera code base and need to be contributed
-upstream by device vendors. IPA modules included in libcamera are covered by a
-free software license, however third-parties may develop IPA modules outside of
-libcamera and distribute them under a closed-source license, provided they do
-not include source code from the libcamera project.
-
-The libcamera project itself contains multiple libraries, applications and
-utilities. Licenses are expressed through SPDX tags in text-based files that
-support comments, and through the .reuse/dep5 file otherwise. A copy of all
-licenses are stored in the LICENSES directory, and a full summary of the
-licensing used throughout the project can be found in the COPYING.rst document.
-
-Applications which link dynamically against libcamera and use only the public
-API are an independent work of the authors and have no license restrictions
-imposed upon them from libcamera.
-
-.. _LGPL-2.1-or-later: https://spdx.org/licenses/LGPL-2.1-or-later.html
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 59416906..6d7d2ca3 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -17,7 +17,6 @@ 
    Application Writer's Guide <guides/application-developer>
    Camera Sensor Model <camera-sensor-model>
    Camera Stack <camera_stack>
-   Developer Guide <guides/introduction>
    Environment variables <environment_variables>
    Feature Requirements <feature_requirements>
    IPA Writer's guide <guides/ipa>
diff --git a/Documentation/meson.build b/Documentation/meson.build
index 74cffc11..32642f32 100644
--- a/Documentation/meson.build
+++ b/Documentation/meson.build
@@ -134,7 +134,6 @@  if sphinx.found()
         'environment_variables.rst',
 	'feature_requirements.rst','
         'guides/application-developer.rst',
-        'guides/introduction.rst',
         'guides/ipa.rst',
         'guides/pipeline-handler.rst',
         'guides/tracing.rst',