Re: [docs] [PATCH] docs: document the conventions used in the manuals

["Antonin Godard" <antonin.godard@bootlin.com>]

Hi,

On Sat Sep 19, 2026 at 8:17 AM CEST, Trevor Woerner wrote:
> On Mon 2026-09-14 @ 06:39:59 PM, Quentin Schulz wrote:
[...]
> having a
> prompt clearly shows what are commands to type and what is output. For
> the sake of uniformity I would rather not have code-block examples that
> have and others that don't have prompts.

I agree.

>
> As for the "what to copy" issue. Every code-block has a "copy" symbol
> that appears in the code-block when you hover over the code-block. If
> the code-block contains things to type with prompts and you click on the
> copy icon of a code-block, the commands are copied and the prompts are
> not. However, if the user highlights what to copy by clicking and
> dragging with the mouse, they will get both the commands as well as the
> prompts. However, that is configurable! It is possible to configure any
> code-block identified as console to not copy the prompts, even when
> clicked-and-dragged with the mouse.

Do you have a working solution for this?

[...]
> Having a "how to use this document" section would explain and codify it
> into our standards, as well as having an author-facing document that
> would give this as an expectation. Review would then be performed
> against these documents for consistency.

Rather than having a document included everywhere, I would rather have a
dedicated section for it in the docs so it is less invasive . It appears in the
sidebar, so a user always sees it too (for HTML docs).

Here's what I have in mind (note the shorter title so it fits in the sidebar):

diff --git a/documentation/index.rst b/documentation/index.rst
index 4bfc40bef..72e51a445 100644
--- a/documentation/index.rst
+++ b/documentation/index.rst
@@ -116,3 +116,10 @@ Release notes and migration guides for the different Yocto Project releases.
    :hidden:
 
    downloads
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Documentation Conventions
+   :hidden:
+
+   conventions
diff --git a/documentation/conventions.rst b/documentation/conventions.rst
new file mode 100644
index 000000000..65061d1a9
--- /dev/null
+++ b/documentation/conventions.rst
@@ -0,0 +1,18 @@
+=========================
+Documentation Conventions
+=========================
+
+Placeholders
+============
+
+Text enclosed in angle brackets is a placeholder. Replace it, including the
+brackets, with a value of your own:
+
+.. code-block:: none
+
+   SRCREV:pn-<recipe> = "${AUTOREV}"
+
+Here, ``<recipe>`` stands for the name of your recipe. A placeholder is
+never text to be copied as it stands, and an example containing one will
+not work until every placeholder in it has been replaced.
+
+...

Thanks,
Antonin