Syntax Highlighting¶

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

.. 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:

.. 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)

.. 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:

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:

# ...
sys.path.append(os.path.abspath('_exts'))

# ...
# 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'