Skip to content
  • About
    • What is Symfony?
    • Community
    • News
    • Contributing
    • Support
  • Documentation
    • Symfony Docs
    • Symfony Book
    • Screencasts
    • Symfony Bundles
    • Symfony Cloud
    • Training
  • Services
    • SensioLabs Professional services to help you with Symfony
    • Platform.sh for Symfony Best platform to deploy Symfony apps
    • SymfonyInsight Automatic quality checks for your apps
    • Symfony Certification Prove your knowledge and boost your career
    • Blackfire Profile and monitor performance of your apps
  • Other
  • Blog
  • Download
sponsored by SensioLabs
  1. Home
  2. Documentation
  3. Contributing
  4. Documentation
  5. Documentation Format
  • Documentation
  • Book
  • Reference
  • Bundles
  • Cloud

Table of Contents

  • reStructuredText
  • Sphinx
    • Syntax Highlighting
    • Configuration Blocks
    • Adding Links
    • New Features, Behavior Changes or Deprecations

Documentation Format

Edit this page

Warning: You are browsing the documentation for Symfony 4.4, which is no longer maintained.

Read the updated version of this page for Symfony 6.2 (the current stable version).

Documentation Format

The Symfony documentation uses reStructuredText as its markup language and Sphinx for generating the documentation in the formats read by the end users, such as HTML and PDF.

reStructuredText

reStructuredText is a plain text 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.

If you want to learn more about this format, check out the reStructuredText Primer tutorial and the reStructuredText Reference.

Caution

If you are familiar with Markdown, be careful as things are sometimes very similar but different:

  • Lists starts at the beginning of a line (no indentation is allowed);
  • Inline code blocks use double-ticks (``like this``).

Sphinx

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 reStructuredText markup. Read more about the Sphinx Markup Constructs.

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

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.

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:

  • YAML
  • XML
  • PHP
1
# Configuration in YAML
1
<!-- Configuration in XML -->
1
// Configuration in PHP

The current list of supported formats are the following:

Markup Format Use It to Display
html HTML
xml XML
php PHP
yaml YAML
twig Pure Twig markup
html+twig Twig markup blended with HTML
html+php PHP code blended with HTML
ini INI
php-annotations PHP Annotations

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

Note

Although they are technically correct, avoid the use of relative internal links such as the following, because they break the references in the generated PDF documentation:

1
2
3
4
5
:doc:`controller`

:doc:`event_dispatcher`

:doc:`environments`

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:: 4.x directive:

1
2
3
.. versionadded:: 4.2

    Named autowiring aliases have been introduced in Symfony 4.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:: 4.2

   Support for ICU MessageFormat was introduced in Symfony 4.2. Prior to this,
   pluralization was managed by the ``transChoice`` method.

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

1
2
3
.. deprecated:: 4.2

    Not passing the root node name to ``TreeBuilder`` was deprecated in Symfony 4.2.

Whenever a new major version of Symfony is released (e.g. 5.0, 6.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 5.0 were released today, 4.0 to 4.4 versionadded and deprecated tags would be removed from the new 5.0 branch.

This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.
TOC
    Version
    We stand with Ukraine.
    Version:
    Become certified from home

    Become certified from home

    Check Code Performance in Dev, Test, Staging & Production

    Check Code Performance in Dev, Test, Staging & Production

    Symfony footer

    ↓ Our footer now uses the colors of the Ukrainian flag because Symfony stands with the people of Ukraine.

    Avatar of Maximilian Zumbansen, a Symfony contributor

    Thanks Maximilian Zumbansen for being a Symfony contributor

    1 commit • 70 lines changed

    View all contributors that help us make Symfony

    Become a Symfony contributor

    Be an active part of the community and contribute ideas, code and bug fixes. Both experts and newcomers are welcome.

    Learn how to contribute

    Symfony™ is a trademark of Symfony SAS. All rights reserved.

    • What is Symfony?

      • Symfony at a Glance
      • Symfony Components
      • Case Studies
      • Symfony Releases
      • Security Policy
      • Logo & Screenshots
      • Trademark & Licenses
      • symfony1 Legacy
    • Learn Symfony

      • Symfony Docs
      • Symfony Book
      • Reference
      • Bundles
      • Best Practices
      • Training
      • eLearning Platform
      • Certification
    • Screencasts

      • Learn Symfony
      • Learn PHP
      • Learn JavaScript
      • Learn Drupal
      • Learn RESTful APIs
    • Community

      • SymfonyConnect
      • Support
      • How to be Involved
      • Code of Conduct
      • Events & Meetups
      • Projects using Symfony
      • Downloads Stats
      • Contributors
      • Backers
    • Blog

      • Events & Meetups
      • A week of symfony
      • Case studies
      • Cloud
      • Community
      • Conferences
      • Diversity
      • Documentation
      • Living on the edge
      • Releases
      • Security Advisories
      • SymfonyInsight
      • Twig
      • SensioLabs
    • Services

      • SensioLabs services
      • Train developers
      • Manage your project quality
      • Improve your project performance
      • Host Symfony projects

      Deployed on

    Follow Symfony

    Search by Algolia