From: michael.opdenacker@bootlin.com
To: docs@lists.yoctoproject.org
Cc: Michael Opdenacker <michael.opdenacker@bootlin.com>
Subject: [kirkstone][PATCH 3/6] documentation: standards.md: align with master branch
Date: Thu, 2 May 2024 08:57:18 +0200 [thread overview]
Message-ID: <20240502065721.22607-4-michael.opdenacker@bootlin.com> (raw)
In-Reply-To: <20240502065721.22607-1-michael.opdenacker@bootlin.com>
From: Michael Opdenacker <michael.opdenacker@bootlin.com>
Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
---
documentation/standards.md | 97 ++++++++++++++++++++++++++++++++++++--
1 file changed, 94 insertions(+), 3 deletions(-)
diff --git a/documentation/standards.md b/documentation/standards.md
index d3b25adfab..bc403e393e 100644
--- a/documentation/standards.md
+++ b/documentation/standards.md
@@ -22,7 +22,92 @@ what Wikipedia or the project defining this word uses.
## Text standards
-This section has not been filled yet
+### Bulleted lists
+
+Though Sphinx supports both the ``*`` and ``-`` characters
+for introducing bulleted lists, we have chosen to use
+only ``-`` for this purpose.
+
+Though not strictly required by Sphinx, we have also chosen
+to use two space characters after ``-`` to introduce each
+list item:
+
+ - Paragraph 1
+
+ - Paragraph 2
+
+As shown in the above example, there should also be an empty
+line between each list item.
+
+An exception to this rule is when the list items are just made
+of a few words, instead of entire paragraphs:
+
+ - Item 1
+ - Item 2
+
+This is again a matter of style, not syntax.
+
+### Line wrapping
+
+Source code for the documentation shouldn't have lines
+wider than 80 characters. This makes patch lines more
+readable and code easier to quote in e-mail clients.
+
+If you have to include long commands or lines in configuration
+files, provided the syntax makes this possible, split them
+into multiple lines, using the ``\`` character.
+
+Here is an example:
+
+ $ scripts/install-buildtools \
+ --without-extended-buildtools \
+ --base-url https://downloads.yoctoproject.org/releases/yocto \
+ --release yocto-4.0.1 \
+ --installer-version 4.0.1
+
+Exceptions are granted for file contents whose lines
+cannot be split without infringing syntactic rules
+or reducing readability, as well as for command output
+which should be kept unmodified.
+
+### File, tool and command names
+
+File, tool, command and package names should be double tick-quoted.
+For example, ``` ``conf/local.conf`` ``` is preferred over
+`"conf/local.conf"`.
+
+### Project names
+
+Project names should be introduced with single quotes, to have them rendered
+with an italic font and make them easier to distinguish from command names
+(double tick-quoted) and from regular English words.
+
+An exception is when project names appear in hyperlinks, as nested markup
+is not supported by Sphinx yet.
+
+Project names should also be capitalized (or not) in the same way they are on
+Wikipedia, or on their own project pages if they are not described on
+Wikipedia. If a project name isn't capitalized, it should remain so even
+at the beginning of a sentence.
+
+For example:
+
+* ``` `BitBake` ```
+* ``` `ftrace` ```
+
+### Variables
+
+Every variable should be mentioned with:
+
+ :term:`VARIABLE`
+
+This assumes that `VARIABLE` is described either
+in the Yocto Project documentation variable index (`ref-manual/variables.rst`)
+or in the BitBake User Manual
+(`doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst`)
+
+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.
## ReStructured Text Syntax standards
@@ -41,8 +126,14 @@ To include a screenshot in PNG format:
.. image:: figures/user-configuration.png
:align: center
-Depending on the size of the image, you may also shrink it
-to prevent it from filling the whole page width:
+A diagram with many details usually needs to use
+the whole page width to be readable on all media.
+In this case, the `:align:` directive is unnecessary:
+
+ :scale: 100%
+
+Conversely, you may also shrink some images to
+to prevent them from filling the whole page width:
:scale: 50%
--
2.34.1
next prev parent reply other threads:[~2024-05-02 6:57 UTC|newest]
Thread overview: 7+ messages / expand[flat|nested] mbox.gz Atom feed top
2024-05-02 6:57 [kirkstone][PATCH 0/6] documentation backports michael.opdenacker
2024-05-02 6:57 ` [kirkstone][PATCH 1/6] ref-manual: variables: Update default INHERIT_DISTRO value michael.opdenacker
2024-05-02 6:57 ` [kirkstone][PATCH 2/6] dev-manual: update custom distribution section michael.opdenacker
2024-05-02 6:57 ` michael.opdenacker [this message]
2024-05-02 6:57 ` [kirkstone][PATCH 4/6] documentation/poky.yaml.in: drop mesa/sdl from essential host packages michael.opdenacker
2024-05-02 6:57 ` [kirkstone][PATCH 5/6] migration-notes: add release notes for 4.0.18 michael.opdenacker
2024-05-02 6:57 ` [kirkstone][PATCH 6/6] ref-manual: update releases.svg michael.opdenacker
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20240502065721.22607-4-michael.opdenacker@bootlin.com \
--to=michael.opdenacker@bootlin.com \
--cc=docs@lists.yoctoproject.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).