| Message ID | 20241118-update-standard-warn-note-v1-1-0407c16b9315@bootlin.com |
|---|---|
| State | New |
| Headers | show |
| Series | [yocto-docs] standards.md: add a section on admonitions | expand |
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
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
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
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(+) --- base-commit: 4e6ff21b414943282a808b90a58edb584f5615e7 change-id: 20241118-update-standard-warn-note-925acaa7d0a8 Best regards,