Colorazione della sintassi¶

Tutti i blocchi di codice utilizzano PHP come linguaggio predefinito. È possibile cambiarlo con la direttiva code-block:

1
2
3

.. code-block:: yaml

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

Se il proprio codice PHP comincia con <?php, allora si avrà bisogno di utilizzare html+php come pseudo-linguaggio:

1
2
3

.. code-block:: html+php

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

Blocchi di configurazione¶

Ogni volta che si mostra una configurazione, per mostrarla in tutti i formati supportati ,bisogna utilizzare la direttiva configuration-block (PHP, YAML e XML):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

.. configuration-block::

    .. code-block:: yaml

        # Configurazione in YAML

    .. code-block:: xml

        <!-- Configurazione in XML //-->

    .. code-block:: php

        // Configurazione in PHP

Il precedente snippet reST mostra un blocco come di seguito:

Ecco la lista dei formati attualmente supportati:

Collegamenti¶

Per aggiungere collegamenti ad altre pagine nei documenti, usare la seguente sintassi:

1

:doc:`/percorso/della/pagina`

Usando il percorso e il nome del file della pagina senza estensione, per esempio:

1
2
3
4
5

:doc:`/book/controller`

:doc:`/components/event_dispatcher/introduction`

:doc:`/cookbook/configuration/environments`

Il testo del collegamento sarà il titolo principale del documento collegato. Si può anche specificare un testo alternativo per il collegamento:

1

:doc:`Spool di email</cookbook/email/spool>`

Si possono anche aggiungere collegamenti alla documentazione delle API:

1
2
3
4
5

:namespace:`Symfony\\Component\\BrowserKit`

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

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

e alla documentazione di PHP:

1
2
3
4
5

:phpclass:`SimpleXMLElement`

`DateTime::createFromFormat`_

:phpfunction:`iterator_to_array`

Test della documentazione¶

Per fare un test della documentazione, prima di un commit:

• Installare Sphinx;
• Eseguire la preparazione rapida di Sphinx;
• Installare le estensioni di Sphinx (vedere sotto);
• Eseguire make html e controllare l'HTML generato nella cartella build.

Installare le estensioni di Sphinx¶

• Scaricare l'estensione dal repository dei sorgenti
• Copiare la cartella sensio nella cartella _exts della propria cartella dei sorgenti (in cui si trova conf.py)
• Aggiungere le righe seguenti al file conf.py:

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

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

# ...
# aggiunge le estensioni alla lista di estensioni
extensions = [..., 'sensio.sphinx.refinclude', 'sensio.sphinx.configurationblock', 'sensio.sphinx.phpcode']

# abilita la colorazione per il codice PHP non compreso tra ``<?php ... ?>``
lexers['php'] = PhpLexer(startinline=True)
lexers['php-annotations'] = PhpLexer(startinline=True)

# usa PHP come dominio primario
primary_domain = 'php'

# imposta url per collegamenti alle API
api_url = 'http://api.symfony.com/master/%s'