diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 3677a2cf..e3549e16 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -3,19 +3,15 @@ Contributing
First of all, **thank you** for contributing, **you are awesome**!
-Here are a few rules to follow in order to ease code reviews, and discussions before
-maintainers accept and merge your work.
+Here are a few rules to follow in order to ease code reviews, and discussions
+before maintainers accept and merge your work:
-You MUST follow the [PSR-1](http://www.php-fig.org/psr/1/) and
-[PSR-2](http://www.php-fig.org/psr/2/). If you don't know about any of them, you
-should really read the recommendations. Can't wait? Use the [PHP-CS-Fixer
-tool](http://cs.sensiolabs.org/).
-
-You MUST run the test suite.
-
-You MUST write (or update) unit tests.
-
-You SHOULD write documentation.
+ * You MUST follow the [PSR-1](http://www.php-fig.org/psr/1/) and
+ [PSR-2](http://www.php-fig.org/psr/2/) recommendations. Use the [PHP-CS-Fixer
+ tool](http://cs.sensiolabs.org/) to fix the syntax of your code automatically.
+ * You MUST run the test suite.
+ * You MUST write (or update) unit tests.
+ * You SHOULD write documentation.
Please, write [commit messages that make
sense](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html),
@@ -31,3 +27,52 @@ Also, while creating your Pull Request on GitHub, you MUST write a description
which gives the context and/or explains why you are creating it.
Thank you!
+
+Running tests
+-------------
+
+Before running the test suite, execute the following Composer command to install
+the dependencies used by the bundle:
+
+```bash
+$ composer install --dev
+```
+
+Then, execute the tests executing:
+
+```bash
+$ phpunit
+```
+
+### JavaScript Test Suite
+
+First, install [PhantomJS](http://phantomjs.org/) and then, execute this command:
+
+```bash
+$ phantomjs Resources/js/run_jsunit.js Resources/js/router_test.html
+```
+
+Compiling the JavaScript files
+------------------------------
+
+> **NOTE**
+>
+> We already provide a compiled version of the JavaScript; this section is only
+> relevant if you want to make changes to this script.
+
+In order to re-compile the JavaScript source files that we ship with this
+bundle, you need the Google Closure Tools. You need the
+[plovr](http://plovr.com/download.html) tool, which is a Java ARchive, so you
+also need a working Java environment. You can re-compile the JavaScript with the
+following command:
+
+```bash
+$ java -jar plovr.jar build Resources/config/plovr/compile.js
+```
+
+Alternatively, you can use the JMSGoogleClosureBundle. If you install this
+bundle, you can re-compile the JavaScript with the following command:
+
+```bash
+$ php app/console plovr:build @FOSJsRoutingBundle/compile.js
+```
diff --git a/Resources/doc/commands.rst b/Resources/doc/commands.rst
new file mode 100644
index 00000000..8308e56c
--- /dev/null
+++ b/Resources/doc/commands.rst
@@ -0,0 +1,58 @@
+Commands
+========
+
+fos:js-routing:dump
+-------------------
+
+This command dumps the route information into a file so that instead of having
+the controller generated JavaScript, you can use a normal file. This also allows
+to combine the routes with the other JavaScript files in assetic.
+
+.. code-block:: bash
+
+ $ php app/console fos:js-routing:dump
+
+Instead of the line
+
+.. code-block:: twig
+
+
+
+you now include this as
+
+.. code-block:: html
+
+
+
+Or inside assetic, do
+
+.. code-block:: twig
+
+ {% javascripts filter='?yui_js'
+ 'bundles/fosjsrouting/js/router.js'
+ 'js/fos_js_routes.js'
+ %}
+
+ {% endjavascripts %}
+
+.. caution::
+
+ You should follow the Symfony documentation about generating URLs
+ in the console: `Configuring The Request Context Globally`_.
+
+.. tip::
+
+ If you are using JMSI18nRoutingBundle, you need to run the command with the
+ ``--locale`` parameter once for each locale you use and adjust your include
+ paths accordingly.
+
+fos:js-routing:debug
+--------------------
+
+This command lists all exposed routes:
+
+.. code-block:: bash
+
+ $ php app/console fos:js-routing:debug [name]
+
+.. _`Configuring The Request Context Globally`: http://symfony.com/doc/current/cookbook/console/sending_emails.html#configuring-the-request-context-globally
diff --git a/Resources/doc/index.md b/Resources/doc/index.md
deleted file mode 100644
index b0824e79..00000000
--- a/Resources/doc/index.md
+++ /dev/null
@@ -1,255 +0,0 @@
-FOSJsRoutingBundle
-==================
-
-Port of the incredible plugin
-[chCmsExposeRoutingPlugin](https://github.com/themouette/chCmsExposeRoutingPlugin).
-
-* [Installation](#installation)
-* [Usage](#usage)
- - [Generating URIs](#generating-uris)
- - [Commands](#commands)
- - [fos:js-routing:dump](#fosjs-routingdump)
- - [fos:js-routing:debug](#fosjs-routingdebug)
- - [HTTP Caching](#http-caching)
-* [Compiling the JavaScript files](#compiling-the-javascript-files)
-
-
-Installation
-------------
-
-Require [`friendsofsymfony/jsrouting-bundle`](https://packagist.org/packages/friendsofsymfony/jsrouting-bundle)
-into your `composer.json` file:
-
-
-``` json
-{
- "require": {
- "friendsofsymfony/jsrouting-bundle": "@stable"
- }
-}
-```
-
-**Protip:** you should browse the
-[`friendsofsymfony/jsrouting-bundle`](https://packagist.org/packages/friendsofsymfony/jsrouting-bundle)
-page to choose a stable version to use, avoid the `@stable` meta constraint.
-
-Register the bundle in `app/AppKernel.php`:
-
-``` php
-// app/AppKernel.php
-public function registerBundles()
-{
- return array(
- // ...
- new FOS\JsRoutingBundle\FOSJsRoutingBundle(),
- );
-}
-```
-
-Register the routing definition in `app/config/routing.yml`:
-
-``` yml
-# app/config/routing.yml
-fos_js_routing:
- resource: "@FOSJsRoutingBundle/Resources/config/routing/routing.xml"
-```
-
-Publish assets:
-
- $ php app/console assets:install --symlink web
-
-
-Usage
------
-
-Add these two lines in your layout:
-
-```
-
-
-```
-
-**Note:** if you are not using Twig, then it is no problem. What you need is to
-add the two JavaScript files above loaded at some point in your web page.
-
-### Generating URIs
-
-It's as simple as calling:
-
-```JavaScript
-Routing.generate('route_id', /* your params */)
-```
-
-Or if you want to generate **absolute URLs**:
-
-```JavaScript
-Routing.generate('route_id', /* your params */, true)
-```
-
-Assuming some route definitions:
-
-```yaml
-# app/config/routing.yml
-my_route_to_expose:
- pattern: /foo/{id}/bar
- defaults: { _controller: HelloBundle:Hello:index }
- options:
- expose: true
-
-my_route_to_expose_with_defaults:
- pattern: /blog/{page}
- defaults: { _controller: AcmeBlogBundle:Blog:index, page: 1 }
- options:
- expose: true
-```
-
-Or using annotations:
-
- # src/Acme/DemoBundle/Controller/DefaultController.php
- /**
- * @Route("/foo/{id}/bar", name="my_route_to_expose", options={"expose"=true})
- */
- public function exposedAction($foo)
-
-You can use the `generate()` method that way:
-
-```JavaScript
-Routing.generate('my_route_to_expose', { id: 10 });
-// will result in /foo/10/bar
-
-Routing.generate('my_route_to_expose', { id: 10, foo: "bar" });
-// will result in /foo/10/bar?foo=bar
-
-$.get(Routing.generate('my_route_to_expose', { id: 10, foo: "bar" }));
-// will call /foo/10/bar?foo=bar
-
-Routing.generate('my_route_to_expose_with_defaults');
-// will result in /blog/1
-
-Routing.generate('my_route_to_expose_with_defaults', { id: 2 });
-// will result in /blog/2
-
-Routing.generate('my_route_to_expose_with_defaults', { foo: "bar" });
-// will result in /blog/1?foo=bar
-
-Routing.generate('my_route_to_expose_with_defaults', { id: 2, foo: "bar" });
-// will result in /blog/2?foo=bar
-```
-
-Moreover, you can configure a list of routes to expose in `app/config/config.yml`:
-
-``` yaml
-# app/config/config.yml
-fos_js_routing:
- routes_to_expose: [ route_1, route_2, ... ]
-```
-
-These routes will be added to the exposed routes. You can use regular expression patterns
-if you don't want to list all your routes name by name.
-
-You can prevent to expose a route by configuring it as below:
-
-```yml
-# app/config/routing.yml
-my_very_secret_route:
- pattern: /admin
- defaults: { _controller: HelloBundle:Admin:index }
- options:
- expose: false
-```
-
-### HTTP Caching
-
-You can enable HTTP caching as below:
-
-```
-# app/config/config.yml
-fos_js_routing:
- cache_control:
- # All are optional, defaults shown
- public: false # can be true (public) or false (private)
- maxage: null # integer value, e.g. 300
- smaxage: null # integer value, e.g. 300
- expires: null # anything that can be fed to "new \DateTime($expires)", e.g. "5 minutes"
- vary: [] # string or array, e.g. "Cookie" or [ Cookie, Accept ]
-```
-
-### Commands
-
-#### fos:js-routing:dump
-
-This command dumps the route information into a file so that instead of having
-the controller generated JavaScript, you can use a normal file. This also allows
-to combine the routes with the other JavaScript files in assetic.
-
- $ php app/console fos:js-routing:dump
-
-Instead of the line
-
-
-
-you now include this as
-
-
-
-Or inside assetic, do
-
- {% javascripts filter='?yui_js'
- 'bundles/fosjsrouting/js/router.js'
- 'js/fos_js_routes.js'
- %}
-
- {% endjavascripts %}
-
-**Important:** you should follow the Symfony documentation about generating URLs
-in the console: [Configuring The Request Context
-Globally](http://symfony.com/doc/current/cookbook/console/sending_emails.html#configuring-the-request-context-globally).
-
-*Hint*: If you are using JMSI18nRoutingBundle, you need to run the command with
-the `--locale` parameter once for each locale you use and adjust your include paths
-accordingly.
-
-
-#### fos:js-routing:debug
-
-This command lists all exposed routes:
-
- $ php app/console fos:js-routing:debug [name]
-
-
-Compiling the JavaScript files
-------------------------------
-
-Note: We already provide a compiled version of the JavaScript; this section is only
-relevant if you want to make changes to this script.
-
-In order to re-compile the JavaScript source files that we ship with this bundle, you
-need the Google Closure Tools. You need the
-[**plovr**](http://plovr.com/download.html) tool, it is a Java ARchive, so you
-also need a working Java environment. You can re-compile the JavaScript with the
-following command:
-
- $ java -jar plovr.jar build Resources/config/plovr/compile.js
-
-Alternatively, you can use the JMSGoogleClosureBundle. If you install this bundle,
-you can re-compile the JavaScript with the following command:
-
- $ php app/console plovr:build @FOSJsRoutingBundle/compile.js
-
-
-Testing
--------
-
-Setup the test suite using [Composer](http://getcomposer.org/):
-
- $ composer install --dev
-
-Run it using PHPUnit:
-
- $ phpunit
-
-### JavaScript Test Suite
-
-You need [PhantomJS](http://phantomjs.org/):
-
- $ phantomjs Resources/js/run_jsunit.js Resources/js/router_test.html
diff --git a/Resources/doc/index.rst b/Resources/doc/index.rst
new file mode 100644
index 00000000..31e4554e
--- /dev/null
+++ b/Resources/doc/index.rst
@@ -0,0 +1,12 @@
+FOSJsRoutingBundle
+==================
+
+This bundle allows to expose Symfony Routes to JavaScript, so you can generate
+relative or absolute URLs in the browser using the same routes as in the backend.
+
+.. toctree::
+ :maxdepth: 1
+
+ installation
+ usage
+ commands
diff --git a/Resources/doc/installation.rst b/Resources/doc/installation.rst
new file mode 100644
index 00000000..4c6107aa
--- /dev/null
+++ b/Resources/doc/installation.rst
@@ -0,0 +1,70 @@
+Installation
+============
+
+Step 1: Download the Bundle
+---------------------------
+
+Open a command console, enter your project directory and execute the
+following command to download the latest stable version of this bundle:
+
+.. code-block:: bash
+
+ $ composer require friendsofsymfony/jsrouting-bundle
+
+This command requires you to have Composer installed globally, as explained
+in the `installation chapter`_ of the Composer documentation.
+
+Step 2: Enable the Bundle
+-------------------------
+
+Then, enable the bundle by adding it to the list of registered bundles
+in the ``app/AppKernel.php`` file of your project:
+
+.. code-block:: php
+
+
+
+
+ .. code-block:: html+php
+
+
+
+
+.. note::
+
+ If you are not using Twig, then it is no problem. What you need is to add
+ the two JavaScript files above loaded at some point in your web page.
+
+Generating URIs
+---------------
+
+It's as simple as calling:
+
+.. code-block:: javascript
+
+ Routing.generate('route_name', /* your params */)
+
+Or if you want to generate **absolute URLs**:
+
+.. code-block:: javascript
+
+ Routing.generate('route_name', /* your params */, true)
+
+Assuming some route definitions:
+
+.. configuration-block::
+
+ .. code-block:: php-annotations
+
+ // src/AppBundle/Controller/DefaultController.php
+
+ /**
+ * @Route("/foo/{id}/bar", options={"expose"=true}, name="my_route_to_expose")
+ */
+ public function indexAction($foo) {
+ // ...
+ }
+
+ /**
+ * @Route("/blog/{page}",
+ * defaults = { "page" = 1 },
+ * options = { "expose" = true },
+ * name = "my_route_to_expose_with_defaults",
+ * )
+ */
+ public function blogAction($page) {
+ // ...
+ }
+
+ .. code-block:: yaml
+
+ # app/config/routing.yml
+ my_route_to_expose:
+ pattern: /foo/{id}/bar
+ defaults: { _controller: AppBundle:Default:index }
+ options:
+ expose: true
+
+ my_route_to_expose_with_defaults:
+ pattern: /blog/{page}
+ defaults: { _controller: AppBundle:Default:blog, page: 1 }
+ options:
+ expose: true
+
+You can use the ``generate()`` method that way:
+
+.. code-block:: javascript
+
+ Routing.generate('my_route_to_expose', { id: 10 });
+ // will result in /foo/10/bar
+
+ Routing.generate('my_route_to_expose', { id: 10, foo: "bar" });
+ // will result in /foo/10/bar?foo=bar
+
+ $.get(Routing.generate('my_route_to_expose', { id: 10, foo: "bar" }));
+ // will call /foo/10/bar?foo=bar
+
+ Routing.generate('my_route_to_expose_with_defaults');
+ // will result in /blog/1
+
+ Routing.generate('my_route_to_expose_with_defaults', { id: 2 });
+ // will result in /blog/2
+
+ Routing.generate('my_route_to_expose_with_defaults', { foo: "bar" });
+ // will result in /blog/1?foo=bar
+
+ Routing.generate('my_route_to_expose_with_defaults', { id: 2, foo: "bar" });
+ // will result in /blog/2?foo=bar
+
+Moreover, you can configure a list of routes to expose in ``app/config/config.yml``:
+
+.. code-block:: yaml
+
+ # app/config/config.yml
+ fos_js_routing:
+ routes_to_expose: [ route_1, route_2, ... ]
+
+These routes will be added to the exposed routes. You can use regular expression
+patterns if you don't want to list all your routes name by name.
+
+You can prevent to expose a route by configuring it as below:
+
+.. code-block:: yaml
+
+ # app/config/routing.yml
+ my_very_secret_route:
+ pattern: /admin
+ defaults: { _controller: HelloBundle:Admin:index }
+ options:
+ expose: false
+
+HTTP Caching
+------------
+
+You can enable HTTP caching as below:
+
+.. code-block:: yaml
+
+ # app/config/config.yml
+ fos_js_routing:
+ cache_control:
+ # All are optional, defaults shown
+ public: false # can be true (public) or false (private)
+ maxage: null # integer value, e.g. 300
+ smaxage: null # integer value, e.g. 300
+ expires: null # anything that can be fed to "new \DateTime($expires)", e.g. "5 minutes"
+ vary: [] # string or array, e.g. "Cookie" or [ Cookie, Accept ]