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

[Trevor Woerner <twoerner@gmail.com>]

The manuals use angle brackets for placeholders and a prompt to mark a
command, and say so nowhere. A reader can only infer both, and one
example reads as advice to paste a line that will not parse.

Add a page stating them, in the sidebar beside the other top-level
entries, so it is reachable from every manual.

AI-Generated: codex/claude-opus 5 (xhigh)
Signed-off-by: Trevor Woerner <twoerner@gmail.com>
---
Changes in v2:
- The page is a document in its own right, reached from a toctree in
  documentation/index.rst, rather than included into each manual's index.
  This is Antonin's suggestion and it is the better shape: the page
  appears in the sidebar of every manual, so a reader meets it wherever
  they are, and the diff touches two files rather than fifteen.
- Retitled "Documentation Conventions", which is short enough for the
  sidebar and matches "Documentation Downloads" beside it. The old title
  said "this document", which no longer describes a standalone page.
- The example showing that a leading "#" is a comment is tagged text
  rather than console. Pygments' console lexer reads a leading "#" as a
  root prompt and lexes the rest of the line as bash, so v1 rendered that
  line as a prompt running a command, with the word "command" coloured as
  a shell builtin - the opposite of what the sentence above it says.
- Added an opening sentence saying the conventions apply throughout the
  documentation, since the page is now landed on directly rather than
  read at the end of a manual.

The wording of both sections is unchanged.

 documentation/conventions.rst | 55 +++++++++++++++++++++++++++++++++++
 documentation/index.rst       |  7 +++++
 2 files changed, 62 insertions(+)
 create mode 100644 documentation/conventions.rst

diff --git a/documentation/conventions.rst b/documentation/conventions.rst
new file mode 100644
index 000000000000..469ad5879b51
--- /dev/null
+++ b/documentation/conventions.rst
@@ -0,0 +1,55 @@
+.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
+
+=========================
+Documentation Conventions
+=========================
+
+These conventions apply throughout the Yocto Project documentation.
+
+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.
+
+Commands and prompts
+====================
+
+Commands are shown with the prompt that runs them, and the prompt is not
+part of the command. Do not type it.
+
+A ``$`` introduces a command you run as your normal user:
+
+.. code-block:: console
+
+   $ bitbake core-image-minimal
+
+Where a command needs administrative privileges on your build host, it is
+shown with ``sudo`` rather than with a root prompt:
+
+.. code-block:: console
+
+   $ sudo apt install gawk
+
+A full prompt ending in ``#`` introduces a command run as ``root``, usually
+on a target machine rather than on your build host:
+
+.. code-block:: console
+
+   root@qemux86-64:~# gdb /bin/cat
+
+Within an example, a line beginning with ``#`` is a comment rather than a
+command:
+
+.. code-block:: text
+
+   # This is a comment, not a command to run as root.
+   $ bitbake core-image-minimal
diff --git a/documentation/index.rst b/documentation/index.rst
index 4bfc40bef070..72e51a4454d7 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
-- 
2.50.0.173.g8b6f19ccfc3a