Symfony
sponsored by SensioLabs
Menu
  • About
  • Documentation
  • Screencasts
  • Cloud
  • Certification
  • Community
  • Businesses
  • News
  • Download
  1. Home
  2. Documentation
  3. Contributing
  4. Documentation
  5. Documentation Format
  • Documentation
  • Book
  • Reference
  • Bundles
  • Cloud
Search by Algolia

Table of Contents

  • reStructuredText
  • Sphinx
    • Syntax Highlighting
    • Configuration Blocks
    • Adding Links
    • Testing Documentation
    • Installing the Sphinx extensions

Documentation Format

Edit this page

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

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

Documentation Format

The Symfony2 documentation uses reStructuredText as its markup language and Sphinx for building the output (HTML, PDF, ...).

reStructuredText

reStructuredText "is an easy-to-read, what-you-see-is-what-you-get plaintext markup syntax and parser system".

You can learn more about its syntax by reading existing Symfony2 documents or by reading the reStructuredText Primer on the Sphinx website.

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 adds some nice tools to create documentation from reStructuredText documents. As such, it adds new directives and interpreted text roles to standard reST markup.

Syntax Highlighting

All code examples uses PHP as the default highlighted language. You can change it with the code-block directive:

1
2
3
.. code-block:: yaml

    { foo: bar, bar: { foo: bar, bar: baz } }

If your PHP code begins with <?php, then you need to use html+php as the highlighted pseudo-language:

1
2
3
.. code-block:: html+php

    <?php echo $this->foobar(); ?>

Note

A list of supported languages is available on the Pygments website.

Configuration Blocks

Whenever you show a configuration, you must use the configuration-block directive to show the configuration in all supported configuration formats (PHP, YAML, and XML)

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 reST 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 Displayed
html HTML
xml XML
php PHP
yaml YAML
jinja Twig
html+jinja Twig
html+php PHP
ini INI
php-annotations Annotations

Adding Links

To add links to other pages in the documents use the following syntax:

1
:doc:`/path/to/page`

Using the path and filename of the page without the extension, for example:

1
2
3
4
5
:doc:`/book/controller`

:doc:`/components/event_dispatcher/introduction`

:doc:`/cookbook/configuration/environments`

The link text will be the main heading of the document linked to. You can also specify alternative text for the link:

1
:doc:`Spooling Email</cookbook/email/spool>`

You can also add links to the API documentation:

1
2
3
4
5
:namespace:`Symfony\\Component\\BrowserKit`

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

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

and to the PHP documentation:

1
2
3
4
5
:phpclass:`SimpleXMLElement`

:phpmethod:`DateTime::createFromFormat`

:phpfunction:`iterator_to_array`

Testing Documentation

To test documentation before a commit:

  • Install Sphinx;
  • Run the Sphinx quick setup;
  • Install the Sphinx extensions (see below);
  • Run make html and view the generated HTML in the build directory.

Installing the Sphinx extensions

  • Download the extension from the source repository
  • Copy the sensio directory to the _exts folder under your source folder (where conf.py is located)
  • Add the following to the conf.py file:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# ...
sys.path.append(os.path.abspath('_exts'))

# adding PhpLexer
from sphinx.highlighting import lexers
from pygments.lexers.web import PhpLexer

# ...
# add the extensions to the list of extensions
extensions = [..., 'sensio.sphinx.refinclude', 'sensio.sphinx.configurationblock', 'sensio.sphinx.phpcode']

# enable highlighting for PHP code not between ``<?php ... ?>`` by default
lexers['php'] = PhpLexer(startinline=True)
lexers['php-annotations'] = PhpLexer(startinline=True)

# use PHP as the primary domain
primary_domain = 'php'

# set url for API links
api_url = 'http://api.symfony.com/master/%s'
This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.
We stand with Ukraine.
Version:
Code consumes server resources. Blackfire tells you how

Code consumes server resources. Blackfire tells you how

Be trained by SensioLabs experts (2 to 6 day sessions -- French or English).

Be trained by SensioLabs experts (2 to 6 day sessions -- French or English).

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

Avatar of Marie Minasyan, a Symfony contributor

Thanks Marie Minasyan (@marie.minassyan) for being a Symfony contributor

5 commits • 58 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