Documentation Format¶

The Sylius documentation uses the 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 Sylius 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 the 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.

The current list of supported formats are the following:

Markup format

Displayed

html

HTML

xml

XML

php

PHP

yaml

YAML

json

JSON

jinja

Twig

html+jinja

Twig

html+php

PHP

ini

INI

php-annotations

Annotations