Documentation Format

Syntax Highlighting

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 } }

Configuration Blocks

Whenever you include a configuration sample, use the configuration-block directive to show the configuration in all supported configuration formats (PHP, YAML and XML). Example:

1
2
3
4
5
6
7
8
9
10
11
12
13

.. configuration-block::

    .. code-block:: yaml

        # Configuration in YAML

    .. code-block:: xml

        <!-- Configuration in XML -->

    .. code-block:: php

        // Configuration in PHP

The previous reStructuredText snippet renders as follow:

1

# Configuration in YAML

1

<!-- Configuration in XML -->

1

// Configuration in PHP

All code examples assume that you are using that feature inside a Symfony application. If you ever need to also show how to use it when working with standalone components in any PHP application, use the special formats php-symfony and php-standalone, which will be rendered like this:

1

// PHP code using features provided by the Symfony framework

1

// PHP code using standalone components

The current list of supported formats are the following:

Displaying Tabs

It is possible to display tabs in the documentation. They look similar to configuration blocks when rendered, but tabs can hold any type of content:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

.. tabs:: UX Installation

    .. tab:: Webpack Encore

        Introduction to Webpack

        .. code-block:: yaml

            webpack:
                # ...

    .. tab:: AssetMapper

        Introduction to AssetMapper

        Something else about AssetMapper

Adding Links

The most common type of links are internal links to other documentation pages, which use the following syntax:

1

:doc:`/absolute/path/to/page`

The page name should not include the file extension (.rst). For example:

1
2
3
4
5

:doc:`/controller`

:doc:`/components/event_dispatcher`

:doc:`/configuration/environments`

The title of the linked page will be automatically used as the text of the link. If you want to modify that title, use this alternative syntax:

1

:doc:`Doctrine Associations </doctrine/associations>`

1
2
3
4
5

:doc:`controller`

:doc:`event_dispatcher`

:doc:`environments`

Links to specific page sections follow a different syntax. First, define a target above section you will link to (syntax: .. _ + target name + :):

1
2
3
4
5
6
7
8
9

# /service_container/autowiring.rst

# define the target
.. _autowiring-calls:

Autowiring other Methods (e.g. Setters and Public Typed Properties)
-------------------------------------------------------------------

// section content ...

Then, use the :ref:: directive to link to that section from another file:

1
2
3

# /reference/attributes.rst

:ref:`Required <autowiring-calls>`

Links to the API follow a different syntax, where you must specify the type of the linked resource (class or method):

1
2
3

:class:`Symfony\\Component\\Routing\\Matcher\\ApacheUrlMatcher`

:method:`Symfony\\Component\\HttpKernel\\Bundle\\Bundle::build`

Links to the PHP documentation follow a pretty similar syntax:

1
2
3
4
5

:phpclass:`SimpleXMLElement`

:phpmethod:`DateTime::createFromFormat`

:phpfunction:`iterator_to_array`

New Features, Behavior Changes or Deprecations

If you are documenting a brand new feature, a change or a deprecation that's been made in Symfony, you should precede your description of the change with the corresponding directive and a short description:

For a new feature or a behavior change use the .. versionadded:: 5.x directive:

1
2
3

.. versionadded:: 5.2

    ... ... ... was introduced in Symfony 5.2.

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

1
2
3
4

.. versionadded:: 5.2

   ... ... ... was introduced in Symfony 5.2. Prior to this,
   ... ... ... ... ... ... ... ... .

For a deprecation use the .. deprecated:: 5.x directive:

1
2
3

.. deprecated:: 5.2

    ... ... ... was deprecated in Symfony 5.2.

Whenever a new major version of Symfony is released (e.g. 6.0, 7.0, etc), a new branch of the documentation is created from the x.4 branch of the previous major version. At this point, all the versionadded and deprecated tags for Symfony versions that have a lower major version will be removed. For example, if Symfony 6.0 were released today, 5.0 to 5.4 versionadded and deprecated tags would be removed from the new 6.0 branch.