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

[Trevor Woerner <twoerner@gmail.com>]

On Mon 2026-09-21 @ 04:34:35 PM, Antonin Godard wrote:
> 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?

Yes (to follow).

> [...]
> > 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).

That works for me; I have a v2 prepared.

> 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