Skip to content

[Contributing] Minor updates in the Docs contributing guide #21440

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Oct 2, 2025
Merged

[Contributing] Minor updates in the Docs contributing guide #21440

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 17 additions & 17 deletions contributing/documentation/standards.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,22 +2,23 @@ Documentation Standards
=======================

Contributions must follow these standards to match the style and tone of the
rest of the Symfony documentation.

Sphinx
------

* The following characters are chosen for different heading levels: level 1
is ``=`` (equal sign), level 2 ``-`` (dash), level 3 ``~`` (tilde), level 4
``.`` (dot) and level 5 ``"`` (double quote);
* Each line should break approximately after the first word that crosses the
72nd character (so most lines end up being 72-78 characters);
* The ``::`` shorthand is *preferred* over ``.. code-block:: php`` to begin a PHP
code block unless it results in the marker being on its own line (read
`the Sphinx documentation`_ to see when you should use the shorthand);
* Inline hyperlinks are **not** used. Separate the link and their target
definition, which you add on the bottom of the page;
* Inline markup should be closed on the same line as the open-string;
rest of the Symfony documentation:

.. _sphinx:

* Use the following characters for each heading level:
* level 1: ``=`` (equal sign),
* level 2: ``-`` (dash),
* level 3: ``~`` (tilde),
* level 4: ``.`` (dot),
* level 5: ``"`` (double quote);
* Break each line at the 80th character whenever possible (e.g. you can ignore
this rule for tables);
* Use the ``::`` shorthand marker instead of ``.. code-block:: php`` to begin a
PHP code block, unless this results in the marker being the only content on its own line;
* Don't use inline hyperlinks. Separate the link and their target definition,
which you add at the bottom of the page;
* Don't extend inline markup formatting (e.g., bold text) across multiple lines.

Example
~~~~~~~
Expand Down Expand Up @@ -223,7 +224,6 @@ In addition, documentation follows these rules:
* **Contractions** are allowed: e.g. you can write ``you would`` as well as ``you'd``,
``it is`` as well as ``it's``, etc.

.. _`the Sphinx documentation`: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#literal-blocks
.. _`Twig Coding Standards`: https://twig.symfony.com/doc/3.x/coding_standards.html
.. _`reserved by the IANA`: https://tools.ietf.org/html/rfc2606#section-3
.. _`American English`: https://en.wikipedia.org/wiki/American_English
Expand Down