Update documentation

Author: wouterj

contributing/documentation/format.rst

@@ -7,25 +7,26 @@ The Symfony2 documentation uses `reStructuredText`_ as its markup language and
 reStructuredText
 ----------------
 
-reStructuredText "is an easy-to-read, what-you-see-is-what-you-get plaintext
-markup syntax and parser system".
+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 are sometimes very
-similar but different:
+.. caution::
 
-* Lists starts at the beginning of a line (no indentation is allowed);
+    If you are familiar with Markdown, be careful as things are sometimes very
+    similar but different:
 
-* Inline code blocks use double-ticks (````like this````).
+    * 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`_.
+interpreted text roles to the standard reST `markup`_.
 
 Syntax Highlighting
 ~~~~~~~~~~~~~~~~~~~
@@ -71,7 +72,7 @@ directive to show the configuration in all supported configuration formats
 
         .. code-block:: xml
 
-            <!-- Configuration in XML //-->
+            <!-- Configuration in XML -->
 
         .. code-block:: php
 
@@ -87,35 +88,29 @@ The previous reST snippet renders as follow:
 
     .. code-block:: xml
 
-        <!-- Configuration in XML //-->
+        <!-- Configuration in XML -->
 
     .. code-block:: 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        |
-+-----------------+-------------+
-| html+php        | PHP         |
-+-----------------+-------------+
-| ini             | INI         |
-+-----------------+-------------+
-| php-annotations | Annotations |
-+-----------------+-------------+
+===============  ==============
+Markup format    Displayed
+===============  ==============
+html             HTML
+xml              XML
+php              PHP
+yaml             YAML
+jinja            Twig
+html+jinja       Twig
+html+php         PHP
+ini              INI
+php-annotations  Annotations
+php-standalone   Standalone Use
+php-symfony      Framework Use
+===============  ==============
 
 Adding Links
 ~~~~~~~~~~~~
@@ -169,53 +164,14 @@ Testing Documentation
 To test documentation before a commit:
 
 * Install `Sphinx`_;
-
-* Run the `Sphinx quick setup`_;
-
-* Install the Sphinx extensions (see below);
-
+* Install the Sphinx extensions using git submodules: ``git submodule update --init``;
+* (Optionally) Install the bundle docs and CMF docs: ``bash install.sh``;
 * 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:
-
-.. code-block:: py
-
-    # ...
-    sys.path.append(os.path.abspath('_exts'))
-
-    # adding PhpLexer
-    from sphinx.highlighting import lexers
-    from pygments.lexers.web import PhpLexer
-
-    # ...
-    # 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)
-    lexers['php-standalone'] = PhpLexer(startinline=True)
-    lexers['php-symfony'] = 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'
-
 .. _reStructuredText:        http://docutils.sourceforge.net/rst.html
 .. _Sphinx:                  http://sphinx-doc.org/
 .. _documents:               https://github.com/symfony/symfony-docs
 .. _reStructuredText Primer: http://sphinx-doc.org/rest.html
 .. _markup:                  http://sphinx-doc.org/markup/
 .. _Pygments website:        http://pygments.org/languages/
-.. _source:                  https://github.com/fabpot/sphinx-php
 .. _Sphinx quick setup:      http://sphinx-doc.org/tutorial.html#setting-up-the-documentation-sources