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

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

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)

.. 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
```
# Configuration in YAML
```
XML
```

```
PHP
```
// 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
jinja+html	Twig
php+html	PHP
html+php	PHP
ini	INI
php-annotations	Annotations

Testing Documentation¶

To test documentation before a commit:

Install Sphinx;

Run the Sphinx quick setup;

Install the configuration-block Sphinx extension (see below);

Run make html and view the generated HTML in the build directory.

Installing the configuration-block Sphinx extension¶

Download the extension from the configuration-block source repository

Copy the configurationblock.py 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 configurationblock to the list of extensions
extensions = ['configurationblock']