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(); ?>

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:

The current list of supported formats are the following:

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'