mbox series

[RFC,0/2] Documentation: Debugging guide

Message ID 20240529-b4-media_docs_improve-v1-0-9ddb111c4433@collabora.com
Headers show
Series Documentation: Debugging guide | expand

Message

Sebastian Fricke May 29, 2024, 4:22 p.m. UTC 
The RFC contains a new summary page for all media related documentation. This
is inspired by other subsystems, which first of all allows a user to find the
subsystem under the subsystems page and secondly eases general navigation
through the documentation that is sprinkled onto multiple places.

Additionally, it provides a guide on how to debug code in the media subsystem.

WHY do we need this?
--------------------

For anyone without years of experience in the Linux kernel, knowing which tool
to use or even which tools are available is not as straightforward as some
senior developers might perceive.
We realized that there is a general need for a kind of "start page", that
allows especially beginners to get up-to-speed with the codebase and the
documentation. The documentation in particular is currently quite hard to navigate
as you mostly have to know what you are searching for to find it.

WHAT do we cover?
-----------------

The document is structured into two sections:

1. A problem-focused approach: This means, a developer facing an issue matching
one of the given examples, will find suggestions for how to approach that
problem (e.g. which tool to use) in this section
2. A tool-focused approach: This sections highlights the available tools, with
comparisions between the tools if sensible. The goal of this work is
**duplicate as little as possible** from the existing documentation and
instead provide a rough overview that provides:
    - A link to the actual documentation
    - A minimal example for how it can be used (from a media perspective,
      if the usage isn't absolutely trivial like printk)
    - A rational for why it should be used

To: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Cc: linux-kernel@vger.kernel.org
Cc: linux-media@vger.kernel.org
Cc: laurent.pinchart@ideasonboard.com
Cc: hverkuil-cisco@xs4all.nl
Cc: mauro.chehab@linux.intel.com
Cc: kernel@collabora.com
Signed-off-by: Sebastian Fricke <sebastian.fricke@collabora.com>

---
Sebastian Fricke (2):
      docs: media: Create separate documentation folder for media
      docs: media: Debugging guide for the media subsystem

 Documentation/media/guides/debugging_issues.rst | 477 ++++++++++++++++++++++++
 Documentation/media/guides/index.rst            |  11 +
 Documentation/media/index.rst                   |  20 +
 Documentation/subsystem-apis.rst                |   1 +
 4 files changed, 509 insertions(+)
---
base-commit: 1613e604df0cd359cf2a7fbd9be7a0bcfacfabd0
change-id: 20240529-b4-media_docs_improve-79ea2d480483

Best regards,