Merge pull request #237 from javiereguiluz/doc_rst

Converted documentation into reStructuredText format

Author: willdurand

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
+```

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
+
+    <script src="{{ path('fos_js_routing_js', {"callback": "fos.Router.setData"}) }}"></script>
+
+you now include this as
+
+.. code-block:: html
+
+    <script src="/js/fos_js_routes.js"></script>
+
+Or inside assetic, do
+
+.. code-block:: twig
+
+    {% javascripts filter='?yui_js'
+        'bundles/fosjsrouting/js/router.js'
+        'js/fos_js_routes.js'
+    %}
+        <script src="{{ asset_url }}"></script>
+    {% 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