Change all content from rst format to markdown and correct spelling/grammar

docs/source/development/menus.md

@@ -0,0 +1,87 @@
+###### Menus
+
+Chill has created his own menu system
+
+   [Routes dans Chill [specification] ](https://redmine.champs-libres.coop/issues/179)
+       The issue wich discussed the implementation of routes.
+
+## Concepts
+
+   to be written
+
+## Add a menu in a template
+
+In your twig template, use the `chill_menu` function :
+
+```php
+   {{ chill_menu('person', {
+	     'layout': 'ChillPersonBundle::menu.html.twig',
+	     'args': {'id': person.id },
+	     'activeRouteKey': 'chill_person_view'
+	}) }}
+```
+
+The available arguments are:
+
+* `layout` : a custom layout. Default to `ChillMainBundle:Menu:defaultMenu.html.twig`
+* `args` : those arguments will be passed through the url generator.
+* `activeRouteKey` must be the route key name.
+
+   The argument `activeRouteKey` may be a twig variable, defined elsewhere in your template, even in child templates.
+
+## Create an entry in an existing menu
+
+If a route belongs to a menu, you simply add this to his definition in routing.yml :
+
+```yaml
+   chill_person_history_list:
+       pattern: /person/{person_id}/history
+       defaults: { _controller: ChillPersonBundle:History:list }
+       options:
+           #declare menus
+           menus:
+               # the route should be in the 'person' menu :
+               person:
+                   #and have those arguments :
+                   order: 100
+                   label: menu.person.history
+```
+
+* `order` (mandatory): the order in the menu. It is preferrable to increment by far more than 1.
+* `label` (mandatory): a translatable string.
+* `helper` (optional): a text to help people to understand what does the menu do. Not used in default implementation.
+* `condition` (optional): an `Expression Language <http://symfony.com/doc/current/components/expression_language/index.html> `_ which will make the menu appears or not. Typically, it may be used to say "show this menu only if the person concerned is more than 18". **Not implemented yet**.
+* `access` (optional): an Expression Language to evalute the possibility, for the user, to show this menu according to Access Control Model. **Not implemented yet.**
+
+You may add additional keys, but should not use the keys described above.
+
+You may add the same route to multiple menus :
+
+```yaml
+   chill_person_history_list:
+       pattern: /person/{person_id}/history
+       defaults: { _controller: ChillPersonBundle:History:list }
+       options:
+           menus:
+               menu1:
+                   order: 100
+                   label: menu.person.history
+               menu2:
+                   order: 100
+                   label: another.label
+```
+
+## Customize menu rendering
+
+You may customize menu rendering by using the `layout` option.
+
+
+   TODO: this part should be written.
+
+## Caveats
+
+Currently, you may pass arguments globally to each menu, and they will be all passed to route url. This means that :
+
+* the argument name in the route entry must match the argument key in the menu declaration in the twig template
+* if an argument is missing to generate an url, the url generator will throw a `Symfony\Component\Routing\Exception\MissingMandatoryParametersException`
+* if the argument name is not declared in route entry, it will be added to the url, (example: `/my/route?additional=foo`)