reStructuredText is a plaintext markup syntax similar to Markdown, but much
stricter with its syntax. If you are new to reStructuredText, take some time to
familiarize with this format by reading the existing Symfony documentation
source code.

Sphinx is a build system that provides tools to create documentation from
reStructuredText documents. As such, it adds new directives and interpreted text
roles to the standard reST markup. Read more about the Sphinx Markup Constructs.

PHP is the default syntax highlighter applied to all code blocks. You can
change it with the code-block directive:

1
2
3

..code-block:: yaml
{ foo: bar, bar: { foo: bar, bar: baz } }

Note

Besides all of the major programming languages, the syntax highlighter
supports all kinds of markup and configuration languages. Check out the
list of supported languages on the syntax highlighter website.

If you're documenting a brand new feature or a change that's been made in
Symfony, you should precede your description of the change with a
.. versionadded:: 2.X directive and a short description:

1
2
3
4

..versionadded:: 2.7
The ``askHiddenResponse()`` method was introduced in Symfony 2.7.
You can also ask a question and hide the response. This is particularly [...]

If you're documenting a behavior change, it may be helpful to briefly describe
how the behavior has changed:

1
2
3

..versionadded:: 2.7
The ``include()`` function is a new Twig feature that's available in
Symfony 2.7. Prior, the ``{% include %}`` tag was used.

Whenever a new minor version of Symfony is released (e.g. 2.4, 2.5, etc),
a new branch of the documentation is created from the master branch.
At this point, all the versionadded tags for Symfony versions that have
reached end-of-maintenance will be removed. For example, if Symfony 2.5 were
released today, and 2.2 had recently reached its end-of-maintenance, the 2.2
versionadded tags would be removed from the new 2.5 branch.