Formato de documentación

La documentación de Symfony2 utiliza reStructuredText como lenguaje de marcado y Sphinx para generarla (en HTML, PDF, ...).

reStructuredText

reStructuredText «es un sistema analizador y sintaxis de marcado de texto, fácil de leer, lo que ves es lo que obtienes».

Puedes aprender más acerca de su sintaxis leyendo los documentos existentes de Symfony2 o leyendo el Primer reStructuredText en el sitio web de Sphinx.

Si estás familiarizado con Markdown, ten cuidado que las cosas a veces se ven muy similares, pero son diferentes:

• Las listas se inician al comienzo de una línea (no se permite sangría);
• Los bloques de código en línea utilizan comillas dobles (``como estas``).

Sphinx

Sphinx es un sistema generador que añade algunas herramientas agradables para crear la documentación a partir de documentos reStructuredText. Como tal, agrega nuevas directivas e interpreta texto en distintos roles al marcado reST estándar.

Resaltado de sintaxis

Todo el código de los ejemplos de manera predeterminada utiliza PHP como lenguaje a resaltar. Puedes cambiarlo con la directiva code-block:

.. code-block:: yaml

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

Si el código PHP comienza con <?php, entonces necesitas usar html+php como pseudolenguaje a resaltar:

.. code-block:: html+php

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

Nota

Una lista de lenguajes apoyados está disponible en el sitio web de Pygments.

Bloques de configuración

Cada vez que muestres una configuración, debes utilizar la directiva configuration-block para mostrar la configuración en todos los formatos de configuración compatibles (YAML, XML y PHP)

.. configuration-block::

    .. code-block:: yaml

        # Configuración en YAML

    .. code-block:: xml

        <!-- Configuración en XML //-->

    .. code-block:: php

        // Configuración en PHP

El fragmento reST anterior se dibuja de la siguiente manera:

• YAML

  # Configuración en YAML
  

• XML

  <!-- Configuración en XML //-->
  

• PHP

  // Configuración en PHP
  

La lista de formatos apoyados actualmente es la siguiente:

Formato de marcado	Muestra
html	HTML
xml	XML
php	PHP
yaml	YAML
jinja	Twig
html+jinja	Twig
html+php	PHP
ini	INI
php-annotations	Anotaciones

Añadiendo enlaces

Para añadir enlaces a otras páginas en los documentos utiliza la siguiente sintaxis:

:doc:`/ruta/a/pagina`

Usando la ruta y nombrearchivo de la página sin extensión, por ejemplo:

:doc:`/book/controller`

:doc:`/components/event_dispatcher/introduction`

:doc:`/cookbook/configuration/environments`

El texto del enlace será el encabezado principal del documento enlazado. También puedes especificar texto alternativo para el enlace:

:doc:`Cola de impresión de correo electrónico </cookbook/email/spool>`

También puedes añadir enlaces a la documentación de la API:

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

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

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

y a la documentación de PHP:

:phpclass:`SimpleXMLElement`

:phpmethod:`DateTime::createFromFormat`

:phpfunction:`iterator_to_array`

Probando la documentación

Para probar la documentación antes de enviarla:

• Instala Sphinx;
• Ejecuta el programa de instalación rápida de Sphinx;
• Instala las extensiones de Sphinx (ve más adelante);
• Ejecuta make html y revisa el código HTML generado en el directorio _build.

Instalando las extensiones de Sphinx

• Descarga las extensiones desde el repositorio source
• Copia el directorio sensio al directorio _exts bajo tu directorio fuente (donde está conf.py)
• Agrega lo siguiente al archivo conf.py:

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

# añadiendo PhpLexer
from sphinx.highlighting import lexers
from pygments.lexers.web import PhpLexer

# ...
# añade la extensión a la lista de extensiones
extensions = [..., 'sensio.sphinx.refinclude',
                   'sensio.sphinx.configurationblock',
                   'sensio.sphinx.phpcode']

# habilita el resaltado para el código PHP que no esté
# entre ``<?php ... ?>`` por omisión
lexers['php'] = PhpLexer(startinline=True)
lexers['php-annotations'] = PhpLexer(startinline=True)

# usa PHP como el dominio primario
primary_domain = 'php'

# fija la url para los enlaces de la API
api_url = 'http://api.symfony.com/master/%s'