[v3,6/7] Documentation: Rework docs.rst into introduction.rst

20955 diff mbox series

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 v2:

	- Renamed docs.rst to introduction.rst
	- Switched to use graphviz extension instead of including an SVG file
	  directly. 
	- Quite a bit of re-wording
	- Kept the camera stack section instead of libcamera architecture

Changes since v1:

	- Removed deleted file from meson's docs_sources array.

 Documentation/conf.py                        |   3 +
 Documentation/documentation-contents.rst     |   1 -
 Documentation/guides/introduction.rst        |  62 -----------
 Documentation/index.rst                      |   3 +-
 Documentation/{docs.rst => introduction.rst} | 110 ++++++++++++++++++-
 Documentation/mali-c55.dot                   |  23 ++++
 Documentation/meson.build                    |   4 +-
 7 files changed, 133 insertions(+), 73 deletions(-)
 delete mode 100644 Documentation/guides/introduction.rst
 rename Documentation/{docs.rst => introduction.rst} (54%)
 create mode 100644 Documentation/mali-c55.dot

Hi Dan,

Thank you for the patch.

On Mon, Aug 19, 2024 at 05:09:20PM +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 v2:
> 
> 	- Renamed docs.rst to introduction.rst
> 	- Switched to use graphviz extension instead of including an SVG file
> 	  directly. 
> 	- Quite a bit of re-wording
> 	- Kept the camera stack section instead of libcamera architecture
> 
> Changes since v1:
> 
> 	- Removed deleted file from meson's docs_sources array.
> 
>  Documentation/conf.py                        |   3 +
>  Documentation/documentation-contents.rst     |   1 -
>  Documentation/guides/introduction.rst        |  62 -----------
>  Documentation/index.rst                      |   3 +-
>  Documentation/{docs.rst => introduction.rst} | 110 ++++++++++++++++++-
>  Documentation/mali-c55.dot                   |  23 ++++
>  Documentation/meson.build                    |   4 +-
>  7 files changed, 133 insertions(+), 73 deletions(-)
>  delete mode 100644 Documentation/guides/introduction.rst
>  rename Documentation/{docs.rst => introduction.rst} (54%)
>  create mode 100644 Documentation/mali-c55.dot
> 
> diff --git a/Documentation/conf.py b/Documentation/conf.py
> index 325f2759..089f114c 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/documentation-contents.rst b/Documentation/documentation-contents.rst
> index c7b78c43..c14389bc 100644
> --- a/Documentation/documentation-contents.rst
> +++ b/Documentation/documentation-contents.rst
> @@ -9,7 +9,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 12d1b7d4..00000000
> --- a/Documentation/guides/introduction.rst
> +++ /dev/null
> @@ -1,62 +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 `Licensing`_ requirements of the project are
> -detailed.
> -
> -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
> -
> -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 95c80b4e..3a790352 100644
> --- a/Documentation/index.rst
> +++ b/Documentation/index.rst
> @@ -10,13 +10,12 @@
>     :caption: Contents:
>  
>     Home <self>
> -   Docs <docs>
> +   Introduction <introduction>
>     Contribute <contributing>
>     Getting Started <getting-started>
>  
>     Application Writer's Guide <guides/application-developer>
>     Camera Sensor Model <camera-sensor-model>
> -   Developer Guide <guides/introduction>
>     Environment variables <environment_variables>
>     Feature Requirements <feature_requirements>
>     IPA Writer's guide <guides/ipa>
> diff --git a/Documentation/docs.rst b/Documentation/introduction.rst
> similarity index 54%
> rename from Documentation/docs.rst
> rename to Documentation/introduction.rst
> index 1f0d12c0..a4994e3c 100644
> --- a/Documentation/docs.rst
> +++ b/Documentation/introduction.rst
> @@ -14,12 +14,88 @@ Documentation
>  
>     API <api-html/index>
>  
> -API
> -===
> -
> -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.
> +What is libcamera?
> +==================
> +
> +libcamera is an open source complex camera support library for Linux, Android
> +and ChromeOS. The library interfaces with Linux kernel 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 is a "complex camera"?
> +===========================
> +
> +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

Line wrap ?

> +'Linux media' subsystem and provides a set of application programming interfaces
> +known collectively as V4L2 (`Video for Linux 2`_) and the `Media Controller`_

s/as V4L2/as the V4L2/

> +APIs which provide an interface to interact and control media devices.

s/APIs/APIs,/

> +
> +.. _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

The sentence is long, maybe

s/ which/, and/

> +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 necessitate bespoke handling.
> +
> +What is libcamera for?
> +======================
> +
> +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:
> +
> +.. graphviz:: mali-c55.dot
> +
> +You can instead simply deal with this:

s/You/you/
s/with this/with/

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

s/And the/The/

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

s/ of course//

> +can find detailed information on how to do so in the
> +:doc:`application writer's guide <guides/application-developer>`.

I may break to a separate paragraph here.

> It may be more

A bit stronger maybe:

s/may/can/

or even "It is often more appropriate"

> +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/might/would/ or 'could'

> +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/
>  
>  Camera Stack
>  ============
> @@ -126,3 +202,25 @@ Native libcamera API
>    followed in the :doc:`Application writer's guide </guides/application-developer>`
>  
>  .. _GStreamer element: https://gstreamer.freedesktop.org/documentation/application-development/basics/elements.html
> +
> +Licensing
> +=========
> +
> +The libcamera core, is covered by the `LGPL-2.1-or-later`_ license. Pipeline

s/core,/core/

> +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/mali-c55.dot b/Documentation/mali-c55.dot
> new file mode 100644
> index 00000000..0b59a488
> --- /dev/null
> +++ b/Documentation/mali-c55.dot
> @@ -0,0 +1,23 @@

Please add a license here.

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

> +digraph board {
> +        rankdir=TB
> +        n00000001 [label="{{} | mali-c55 tpg\n/dev/v4l-subdev0 | {<port0> 0}}", shape=Mrecord, style=filled, fillcolor=green]
> +        n00000001:port0 -> n00000003:port0 [style=dashed]
> +        n00000003 [label="{{<port0> 0 | <port4> 4} | mali-c55 isp\n/dev/v4l-subdev1 | {<port1> 1 | <port2> 2 | <port3> 3}}", shape=Mrecord, style=filled, fillcolor=green]
> +        n00000003:port1 -> n00000009:port0 [style=bold]
> +        n00000003:port2 -> n00000009:port2 [style=bold]
> +        n00000003:port1 -> n0000000d:port0 [style=bold]
> +        n00000003:port3 -> n0000001c
> +        n00000009 [label="{{<port0> 0 | <port2> 2} | mali-c55 resizer fr\n/dev/v4l-subdev2 | {<port1> 1}}", shape=Mrecord, style=filled, fillcolor=green]
> +        n00000009:port1 -> n00000010
> +        n0000000d [label="{{<port0> 0} | mali-c55 resizer ds\n/dev/v4l-subdev3 | {<port1> 1}}", shape=Mrecord, style=filled, fillcolor=green]
> +        n0000000d:port1 -> n00000014
> +        n00000010 [label="mali-c55 fr\n/dev/video0", shape=box, style=filled, fillcolor=yellow]
> +        n00000014 [label="mali-c55 ds\n/dev/video1", shape=box, style=filled, fillcolor=yellow]
> +        n00000018 [label="mali-c55 3a params\n/dev/video2", shape=box, style=filled, fillcolor=yellow]
> +        n00000018 -> n00000003:port4
> +        n0000001c [label="mali-c55 3a stats\n/dev/video3", shape=box, style=filled, fillcolor=yellow]
> +        n00000030 [label="{{<port0> 0} | lte-csi2-rx\n/dev/v4l-subdev4 | {<port1> 1}}", shape=Mrecord, style=filled, fillcolor=green]
> +        n00000030:port1 -> n00000003:port0
> +        n00000035 [label="{{} | imx415 1-001a\n/dev/v4l-subdev5 | {<port0> 0}}", shape=Mrecord, style=filled, fillcolor=green]
> +        n00000035:port0 -> n00000030:port0 [style=bold]
> +}
> diff --git a/Documentation/meson.build b/Documentation/meson.build
> index 54788d6d..36ffae23 100644
> --- a/Documentation/meson.build
> +++ b/Documentation/meson.build
> @@ -128,18 +128,18 @@ if sphinx.found()
>          'coding-style.rst',
>          'conf.py',
>          'contributing.rst',
> -        'docs.rst',
>          'documentation-contents.rst',
>          'environment_variables.rst',
>          'feature_requirements.rst',
>          'guides/application-developer.rst',
> -        'guides/introduction.rst',
>          'guides/ipa.rst',
>          'guides/pipeline-handler.rst',
>          'guides/tracing.rst',
>          'index.rst',
> +        'introduction.rst',
>          'lens_driver_requirements.rst',
>          'libcamera_architecture.rst',
> +        'mali-c55.dot',
>          'python-bindings.rst',
>          'sensor_driver_requirements.rst',
>          'software-isp-benchmarking.rst',