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 <quentin.schulz@cherry.de>
Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>
(From yocto-docs rev: 845983eed77f9914994375eff11ea5c9bb690593)

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
(cherry picked from commit a37bb6cbb67f923206c5c168b5239527530fbce5)
Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
Signed-off-by: Steve Sakoman <steve@sakoman.com>

1 files changed, 15 insertions, 0 deletions

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