From 129756e664a2dfc3695ed42d48423a99c9b7478e Mon Sep 17 00:00:00 2001 From: Antonin Godard Date: Mon, 18 Nov 2024 15:24:01 +0100 Subject: [PATCH] standards.md: add a section on admonitions We try to limit our usage of these admonitions to `note` and `warning`, as the Sphinx documentation warns that most themes only style these two admonitions. So add a section on that. Suggested-by: Quentin Schulz Reviewed-by: Quentin Schulz (From yocto-docs rev: 0c1252b67e602ebf7197e1388dd1fb86b37d25c8) Signed-off-by: Antonin Godard Signed-off-by: Richard Purdie --- documentation/standards.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/documentation/standards.md b/documentation/standards.md index bc403e393e..f3d88d446b 100644 --- a/documentation/standards.md +++ b/documentation/standards.md @@ -109,6 +109,21 @@ or in the BitBake User Manual If it is not described yet, the variable should be added to the glossary before or in the same patch it is used, so that `:term:` can be used. +### Admonitions + +Sphinx has predefined admonitions that can be used to highlight a bit of text or +add a side-note to the documentation. For example: + +```rst +.. note:: + + This is a note admonition. +``` + +We try to limit our usage of these admonitions to `note` and `warning`, as the +Sphinx documentation [warns](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#directives) +that most themes only style these two admonitions. + ## ReStructured Text Syntax standards This section has not been filled yet