@@ -2,22 +2,23 @@ Documentation Standards
22=======================
33
44Contributions must follow these standards to match the style and tone of the
5- rest of the Symfony documentation.
6-
7- Sphinx
8- ------
9-
10- * The following characters are chosen for different heading levels: level 1
11- is ``= `` (equal sign), level 2 ``- `` (dash), level 3 ``~ `` (tilde), level 4
12- ``. `` (dot) and level 5 ``" `` (double quote);
13- * Each line should break approximately after the first word that crosses the
14- 72nd character (so most lines end up being 72-78 characters);
15- * The ``:: `` shorthand is *preferred * over ``.. code-block:: php `` to begin a PHP
16- code block unless it results in the marker being on its own line (read
17- `the Sphinx documentation `_ to see when you should use the shorthand);
18- * Inline hyperlinks are **not ** used. Separate the link and their target
19- definition, which you add on the bottom of the page;
20- * Inline markup should be closed on the same line as the open-string;
5+ rest of the Symfony documentation:
6+
7+ .. _sphinx :
8+
9+ * Use the following characters for each heading level:
10+ * level 1: ``= `` (equal sign),
11+ * level 2: ``- `` (dash),
12+ * level 3: ``~ `` (tilde),
13+ * level 4: ``. `` (dot),
14+ * level 5: ``" `` (double quote);
15+ * Break each line at the 80th character whenever possible (e.g. you can ignore
16+ this rule for tables);
17+ * Use the ``:: `` shorthand marker instead of ``.. code-block:: php `` to begin a
18+ PHP code block, unless this results in the marker being the only content on its own line;
19+ * Don't use inline hyperlinks. Separate the link and their target definition,
20+ which you add at the bottom of the page;
21+ * Don't extend inline markup formatting (e.g., bold text) across multiple lines.
2122
2223Example
2324~~~~~~~
@@ -223,7 +224,6 @@ In addition, documentation follows these rules:
223224* **Contractions ** are allowed: e.g. you can write ``you would `` as well as ``you'd ``,
224225 ``it is `` as well as ``it's ``, etc.
225226
226- .. _`the Sphinx documentation` : https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#literal-blocks
227227.. _`Twig Coding Standards` : https://twig.symfony.com/doc/3.x/coding_standards.html
228228.. _`reserved by the IANA` : https://tools.ietf.org/html/rfc2606#section-3
229229.. _`American English` : https://en.wikipedia.org/wiki/American_English
0 commit comments