[yocto-docs PATCH] standards.md: add a section on admonitions

[yocto-docs PATCH] standards.md: add a section on admonitions

[Antonin Godard]

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>
Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 documentation/standards.md | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/documentation/standards.md b/documentation/standards.md
index bc403e393e9a014daf0403b42197f3b71c75187b..f3d88d446b850ea015bd41ecef122afec490f4d3 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

---
base-commit: 4e6ff21b414943282a808b90a58edb584f5615e7
change-id: 20241118-update-standard-warn-note-925acaa7d0a8

Best regards,
-- 
Antonin Godard <antonin.godard@bootlin.com>

Re: [yocto-docs PATCH] standards.md: add a section on admonitions

[Quentin Schulz]

Hi Antonin,

On 11/18/24 3:24 PM, Antonin Godard wrote:
> 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>
> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>

Looks good to me,

Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>

Thanks!
Quentin

Re: [yocto-docs PATCH] standards.md: add a section on admonitions

[Antonin Godard]

Hi Quentin,

On Mon Nov 18, 2024 at 4:22 PM CET, Quentin Schulz wrote:
> Hi Antonin,
>
> On 11/18/24 3:24 PM, Antonin Godard wrote:
>> 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>
>> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
>
> Looks good to me,
>
> Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>
>
> Thanks!
> Quentin

Thank you!
Antonin

-- 
Antonin Godard, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com