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

.changes/unreleased/DX-20251117-160650.yaml

@@ -0,0 +1,6 @@
+kind: DX
+body: Use mkdocs instead of sphinx to build chill developer documentation
+time: 2025-11-17T16:06:50.46185765+01:00
+custom:
+    Issue: "386"
+    SchemaChange: No schema change

docs/Makefile

@@ -1,25 +1,16 @@
-# Makefile for Sphinx documentation
+# Makefile for MkDocs documentation
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    =
-SPHINXBUILD   = sphinx-build
-PAPER         =
-BUILDDIR      = build
+MKDOCS       = mkdocs
+BUILDDIR     = site
 
-# User-friendly check for sphinx-build
-ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
-$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
+# User-friendly check for mkdocs
+ifeq ($(shell which $(MKDOCS) >/dev/null 2>&1; echo $$?), 1)
+$(error The '$(MKDOCS)' command was not found. Make sure you have MkDocs installed with 'pip install mkdocs mkdocs-material', then make sure the mkdocs executable is in your PATH.)
 endif
 
-# Internal variables.
-PAPEROPT_a4     = -D latex_paper_size=a4
-PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
-# the i18n builder cannot share the environment and doctrees with the others
-I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
-
-.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+.PHONY: help clean html serve build
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"

docs/README.md

@@ -10,20 +10,26 @@ Compilation into HTML
 
 To compile this documentation :
 
-1. Install [sphinx-doc](http://sphinx-doc.org)
+1. Install [MkDocs](https://www.mkdocs.org/) and MkDocs Material
     ``` bash
             $ virtualenv .venv # creation of the virtual env (only the first time)
             $ source .venv/bin/activate # activate the virtual env
     (.venv) $ pip install -r requirements.txt
     ```
 2. Install submodules : $ git submodule update --init;
-3. run `make html` from the root directory
-4. The base file is located on build/html/index.html
+3. run `make html` or `mkdocs build` from the root directory
+4. The base file is located on site/index.html
     ``` bash
-    $ cd build/html
+    $ cd site
     $ python -m http.server 8888 # will serve the site on the port 8888
     ```
 
+Alternatively, you can use the built-in development server:
+``` bash
+(.venv) $ mkdocs serve
+```
+This will start a development server at http://127.0.0.1:8000/ with live reload.
+
 Contribute
 ===========
 

docs/mkdocs.yml

@@ -0,0 +1,137 @@
+site_name: Chill Documentation
+site_description: Documentation for Chill - A free software for social workers
+site_url: https://docs.chill.social
+repo_url: https://gitlab.com/Chill-project/chill-bundles
+repo_name: Chill-project/chill-bundles
+
+docs_dir: source
+
+copyright: Copyright © 2014-2024 Champs-Libres Cooperative SCRLFS - GNU Free Documentation License v1.3
+
+theme:
+  name: material
+  language: en
+  features:
+    - navigation.tabs
+    - navigation.tabs.sticky
+    - navigation.sections
+    - navigation.expand
+    - navigation.path
+    - navigation.top
+    - search.highlight
+    - search.share
+    - search.suggest
+    - toc.follow
+    - content.code.copy
+    - content.code.annotate
+
+  palette:
+    # Palette toggle for light mode
+    - scheme: default
+      primary: blue
+      accent: blue
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+
+    # Palette toggle for dark mode
+    - scheme: slate
+      primary: blue
+      accent: blue
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+
+  font:
+    text: Roboto
+    code: Roboto Mono
+
+plugins:
+  - search
+  - autorefs
+
+markdown_extensions:
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - toc:
+      permalink: true
+  - tables
+  - attr_list
+  - md_in_html
+
+nav:
+  - Home: index.md
+  - Installation:
+    - installation/index.md
+    - Development: installation/installation-development.md
+    - Production: installation/installation-production.md
+    - Document Storage: installation/document-storage.md
+    - Load Addresses: installation/load-addresses.md
+    - Production Setup: installation/prod.md
+    - Calendar SMS: installation/prod-calendar-sms-sending.md
+    - MS Graph Configuration: installation/msgraph-configure.md
+    - Enable Collabora: installation/enable-collabora-for-dev.md
+  - Development:
+    - development/index.md
+    - Access Control: development/access_control_model.md
+    - API: development/api.md
+    - Assets: development/assets.md
+    - Code Quality: development/code-quality.md
+    - Create Bundle: development/create-a-new-bundle.md
+    - Cronjobs: development/cronjob.md
+    - CRUD: development/crud.md
+    - Database Principles: development/database-principles.md
+    - Embeddable Comments: development/embeddable-comments.md
+    - Entity Info: development/entity-info.md
+    - ESLint: development/es-lint.md
+    - Exports: development/exports.md
+    - FAQ: development/FAQ.md
+    - Forms: development/forms.md
+    - Localisation: development/localisation.md
+    - Logging: development/logging.md
+    - Manual:
+      - development/manual/index.md
+      - Routing and Menus: development/manual/routing-and-menus.md
+    - Menus: development/menus.md
+    - Messages to Users: development/messages-to-users.md
+    - Migrations: development/migrations.md
+    - Pagination: development/pagination.md
+    - Render Entity: development/render-entity.md
+    - Routing: development/routing.md
+    - Run Tests: development/run-tests.md
+    - Searching: development/searching.md
+    - Timelines: development/timelines.md
+    - Useful Snippets: development/useful-snippets.md
+    - User Interface:
+      - CSS Classes: development/user-interface/css-classes.md
+      - JS Functions: development/user-interface/js-functions.md
+      - Layout Template: development/user-interface/layout-template-usage.md
+      - Widgets: development/user-interface/widgets.md
+  - Bundles:
+    - bundles/index.md
+    - Activity: bundles/activity.md
+    - Custom Fields: bundles/custom-fields.md
+    - Event: bundles/event.md
+    - Group: bundles/group.md
+    - LDAP: bundles/ldap.md
+    - Main: bundles/main.md
+    - Person: bundles/person.md
+    - Report: bundles/report.md
+
+extra:
+  social:
+    - icon: fontawesome/brands/gitlab
+      link: https://gitlab.com/Chill-project
+    - icon: fontawesome/solid/comments
+      link: https://app.element.io/#/room/#chill-social-admin:matrix.org

docs/requirements.txt

@@ -1,7 +1,4 @@
-docutils==0.13.1
-Pygments==2.2.0
-sphinx==1.8.5
-Jinja2<3.1
-git+https://github.com/fabpot/sphinx-php.git@v2.0.2#egg_name=sphinx-php
-jsx-lexer===0.0.8
-sphinx_rtd_theme==0.5.0
+mkdocs>=1.5.0
+mkdocs-material>=9.4.0
+pymdown-extensions>=10.3.0
+mkdocs-autorefs>=0.5.0

docs/source/bundles/activity.md

@@ -0,0 +1,55 @@
+Permission is granted to copy, distribute and/or modify this document
+   under the terms of the GNU Free Documentation License, Version 1.3
+   or any later version published by the Free Software Foundation;
+   with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+   A copy of the license is included in the section entitled "GNU
+   Free Documentation License".
+
+# Activity bundle
+
+This bundle provides the ability to record people in the software. This bundle is required by other bundle.
+
+   :local:
+
+###### Entities provided
+
+   Describe the entities provided.
+
+###### Configuration options
+
+Those options are available under `chill_activity` key.
+
+Example of configuration:
+
+   chill_activity:
+      form:
+         time_duration:
+            - { label: '12 minutes', seconds: 720 }
+            - { label: '30 minutes', seconds: 1800 }
+
+form.time_duration *array*
+   The duration which might be suggested when the user create or update an activity. The value must be an array of object, where each object must have a `label` and a `seconds` key. The label provide which is shown to user (the label will be translated, if possible) and the seconds the duration.
+
+   Example: see the example above
+
+   Default value: the values available are 5, 10, 15, 20, 25, 30, 45 minutes, and 1 hour, 1 hour 15, 1 hour 30, 1 hour 45 and 2 hours.
+
+###### Macros
+
+## Activity reason sticker
+
+Macro file
+   `ChillActivityBundle:ActivityReason:macro.html.twig`
+Macro envelope
+   `reason(r)`
+
+   `p` is an instance of :class:`Chill\ActivityBundle\Entity\ActivityReason`
+
+When to use this macro ?
+   When you want to represent an activity reason.
+Example usage :
+   ```jinja
+   {% import 'ChillActivityBundle:ActivityReason:macro.html.twig' as m %}
+
+   {{ m.reason(r) }}
+   ```

docs/source/bundles/custom-fields.md

@@ -0,0 +1,381 @@
+Permission is granted to copy, distribute and/or modify this document
+   under the terms of the GNU Free Documentation License, Version 1.3
+   or any later version published by the Free Software Foundation;
+   with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+   A copy of the license is included in the section entitled "GNU
+   Free Documentation License".
+   
+
+## Custom fields bundle
+
+This bundle provides the ability to add custom fields to existing entities.
+
+Those custom fields contains extra data and will be stored in the DB, along with other data's entities. It may be string, text, date, ... or a link to an existing entities.
+
+In the database, custom fields are stored in json format.
+
+   The full specification discussed [here. ](https://redmine.champs-libres.coop/issues/239)
+   
+   [JSON Type on postgresql documentation ](http://www.postgresql.org/docs/9.3/static/datatype-json.html)
+      The documentation of json type, which is used to store data in the database.
+   
+
+   :depth: 4
+   :local:
+
+### Custom Fields concepts
+
+Custom fields are extra data which may be added to entities by user. If a developer implements custom fields on a entity, users will be able to add more fields on this entity.
+
+Example: the [person bundle` allows to record `firstname`, `lastname`, `date of birth` fields. But users need to store information about the kind of house he has (if he owns his house, if he rents it, ...). Custom fields allows to create those fields.
+
+Automatically, those fields are added at the person form. They are also printed in the person view and in exports.
+
+##### Custom fields and custom fields group
+
+Custom fields are associated to a custom fields group. When a user want to add custom fields on an entity, he must first create a custom fields group and associate this field with an entity. Then he may add add custom fields to this groups. 
+
+Some entities needs a **default** custom fields group. For instance, the default custom fields group will be printed on the main form for person, and will be appended on the main person view. Some bundle does not use this feature (i.e. the `report` bundle).
+
+   In the future of the `person bundle`, other custom fields group will be added in forms accessible from the menu, allowing users to completely customize and separate their entities.
+   
+### Allow custom fields on an entity
+
+As a developer, you must allow your users to add custom fields on your entities.
+
+    For having custom fields, the class of the entity must contain a variable for storing the custom data. **By convention this variable must be called $cFData**
+
+##### Create a json field on your entity
+
+Declare a json field in your database :
+
+   Chill\CustomFieldsBundle\Entity\BlopEntity:
+      type: entity
+      # ...
+      fields:
+         cFData:
+            type: json_array
+            
+Create the field accordingly in the class logic :
+
+   namespace Chill\CustomFieldsBundle\Entity;
+   
+   /**
+   * BlopEntity
+   */
+   class BlopEntity
+   {
+   
+   /**
+   * @var array
+   */
+   private $cFData;
+   
+   /**
+   * You must set a setter in order to save automatically custom 
+   * fields from forms, using Form Component
+   *
+   * @param array $cFData
+   * @return BlopEntity
+   */
+   public function setCFData(array $cFData)
+   {
+      $this->cFData = $cFData;
+      return $this;
+   }
+   
+   /**
+   * You also must create a getter in order to let Form 
+   * component populate form fields
+   *
+   * @return array
+   */
+   public function getCFData()
+   {
+      return $this->cFData;
+   }
+            
+##### Declare your customizable entity in configuration
+
+This step is necessary to allow user to create custom fields group associated with this entity.
+
+Two methods are available.
+
+The recommended method is to do it in DependencyInjection/Extension class. It is recommended as your bundle will be well set up (for custom field) in every chill installation that use it.
+
+The discouraged method is to declare via the app/config.yml file. This is very quick to set up for a given chill installation but it is not done automatically : in every chill installation that use your bundle, this step has to be performed.
+
+In app/config.yml file (discouraged)
+""""""""""""""""""""""""""""""""""""
+
+This method is discouraged but explained first as it helps to undersand the recommended method.
+
+Add those file under `chill_custom_fields` section :
+
+   chill_custom_fields:
+      customizables_entities:
+         - { class: Chill\YourBundleBundle\Entity\BlopEntity, name: blop_entity }
+         
+* The `name` allow you to define a string which is translatable. This string will appears when chill's admin will add/retrieve new customFieldsGroup.
+* The class, which is a full FQDN class path
+
+Automatically, in DependencyInjection/Extension class (recommended)
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+This is the recommended way for declaring customizable classes. 
+
+You can prepend configuration of `custom fields bundle` from the class `YourBundle\DependencyInjection\YourBundleExtension`. **Note** that you also have to implements `Symfony\Component\DependencyInjection\Extension\PrependExtensionInterface` on this class to make the `prepend` function being taken into account.
+
+Example here : 
+
+    class ChillYourBundleExtension extends Extension implements PrependExtensionInterface
+    {
+        /**
+         * @param ContainerBuilder $container
+         */
+        public function prepend(ContainerBuilder $container)
+        {
+            $bundles = $container->getParameter('kernel.bundles');
+            if (!isset($bundles['ChillCustomFieldsBundle'])) {
+                throw new MissingBundleException('ChillCustomFieldsBundle');
+            }
+
+            $container->prependExtensionConfig('chill_custom_fields',
+                array('customizables_entities' => 
+                    array(
+                        array(
+                            'class' => 'Chill\YourBundleBundle\Entity\BlopEntity', 
+                            'name' => 'blop_entity',)
+                   )
+               )
+            );
+        }
+    }
+
+* The `name` allow you to define a string which is translatable. This string will appears when chill's admin will add/retrieve new customFieldsGroup.
+* The class, which is a full FQDN class path
+
+   `How to simplify configuration of multiple bundles ](http://symfony.com/doc/current/cookbook/bundles/prepend_extension.html)
+      A cookbook page about prepending configuration.
+
+##### Adding options to your custom fields groups
+
+You may add options to the groups associated with an entity.
+
+In `config.yml` the declaration should be : 
+
+   chill_custom_fields:
+       customizables_entities:
+           - 
+               class: Chill\YourBundleBundle\Entity\BlopEntity
+               name: BlopEntity
+               options:
+                   # this will create a "myFieldKey" field as text, with a maxlength attribute to 150 (see http://symfony.com/doc/master/reference/forms/types/text.html)
+                   myFieldKey: {form_type: text, form_options: {attr: [maxlength: 150]}} 
+
+In the `PrependExtensionInterface::prepend` function, the options key will be added in the configuration definition : 
+
+   class ChillYourBundleExtension extends Extension implements PrependExtensionInterface
+   {
+       /**
+        * @param ContainerBuilder $container
+        */
+       public function prepend(ContainerBuilder $container)
+       {
+           $bundles = $container->getParameter('kernel.bundles');
+           if (!isset($bundles['ChillCustomFieldsBundle'])) {
+               throw new MissingBundleException('ChillCustomFieldsBundle');
+           }
+
+           $container->prependExtensionConfig('chill_custom_fields',
+               array('customizables_entities' => 
+                   array(
+                       array(
+                          'class' => 'Chill\YourBundleBundle\Entity\BlopEntity', 
+                          'name' => 'BlopEntity',
+                          'options' => array(
+                                'myFieldKey' => [ 'form_type' => 'text', 'form_options' => [ 'attr' => [ 'maxlength' => 150 ] ]
+                          ))
+                   )
+               )
+           );
+       }
+   }
+               
+**Example :** the entity `Report` from **ReportBundle** has to pick some custom fields belonging to a group to print them in *summaries* the timeline page. The definition will use the special type `custom_fields_group_linked_custom_field` which will add a select input with all fields associated with the current custom fields group : 
+
+   class ChillReportExtension extends Extension implements PrependExtensionInterface
+   {
+       /**
+###### *
+        * @param ContainerBuilder $container
+        */
+       public function prepend(ContainerBuilder $container)
+       {
+           $bundles = $container->getParameter('kernel.bundles');
+           if (!isset($bundles['ChillCustomFieldsBundle'])) {
+               throw new MissingBundleException('ChillCustomFieldsBundle');
+           }
+
+           $container->prependExtensionConfig('chill_custom_fields',
+               array('customizables_entities' => 
+                   array(
+                       array(
+                          'class' => 'Chill\ReportBundle\Entity\Report', 
+                          'name' => 'ReportEntity',
+                          'options' => array(
+                             'summary_fields' => array(
+                                'form_type' => 'custom_fields_group_linked_custom_fields',
+                                'form_options' => 
+                                   [
+                                      'multiple' => true,
+                                      'expanded' => false
+                                   ]
+                             )
+                          ))
+                   )
+               )
+           );
+       }
+   }
+
+Note that `custom_fields_group_linked_custom_fields` does not create any input on `CustomFieldsGroup` creation : there aren't any fields associated with the custom fields just after the group creation... You have to add custom fields and associate them with the newly created group to see them appears.
+
+### Rendering custom fields and custom fields group in a template
+
+    Each custom field can be `active` or not. Only `active` custom fields has to be dislayed.
+
+For rendering custom fields, two function are available :
+
+* `chill_custom_field_widget` to render the widget. This function is defined on a customFieldType basis.
+* `chill_custom_field_label` to render the label. You can customize the label rendering by choosing the layout you would like to use.
+* `chill_custom_field_is_empty` indicates if the content of the custom fields is empty (return a boolean)
+
+For rendering custom fields group, a function is available :
+
+* `chill_custom_fields_group_widget` to render the widget. It will display the custom fields of the group in a dd / dt structure.
+
+##### chill_custom_field_label
+
+The signature is :
+
+* `CustomField` **$customField** a customField instance
+* `array` **params** the parameters for rendering. Currently, 'label_layout' allow to choose a different label. Default is 'ChillCustomFieldsBundle:CustomField:render_label.html.twig'
+
+Examples
+
+   {{ chill_custom_field_label(customField) }}
+
+##### chill_custom_field_widget
+
+The signature is :
+
+*  array **$fields** the array raw, as stored in the db
+*  CustomField **$customField** a customField instance 
+*  string **$documentType** the type of document. Default to `html`.
+
+Examples:
+
+   {{ chill_custom_field_widget(entity.customFields, customField) }}
+
+##### chill_custom_field_is_empty
+
+The signature is :
+
+* array **$fields** the array raw, as stored in the db
+* CustomField **$customField** a customField instance
+
+Examples :
+
+   {%- if chill_custom_field_is_empty(cFData, customField) == false -%}
+
+##### chill_custom_fields_group_widget
+
+This function only display custom fields that are `active`.
+
+The signature is :
+
+*  array **$fields** the array raw, as stored in the db
+*  CustomFieldsGroup **$customFieldsGroup** the custom field group to render
+
+   {{ chill_custom_fields_group_widget(entity.cFData, entity.customFieldsGroup) }}
+
+### Custom Fields's form
+
+You should simply use the 'custom_field' type in a template, with the group you would like to render in the `group` option's type.
+
+Example : 
+
+   namespace Chill\ReportBundle\Form;
+
+   use Symfony\Component\Form\AbstractType;
+   use Symfony\Component\Form\FormBuilderInterface;
+   use Symfony\Component\OptionsResolver\OptionsResolverInterface;
+
+   class ReportType extends AbstractType
+   {
+       /**
+        * @param FormBuilderInterface $builder
+        * @param array $options
+        */
+       public function buildForm(FormBuilderInterface $builder, array $options)
+       {
+           $entityManager = $options['em'];
+
+           $builder
+               ->add('user')
+               ->add('date', 'date', 
+                   array('required' => true, 'widget' => 'single_text', 'format' => 'dd-MM-yyyy'))
+               #add the custom fields :
+               ->add('cFData', 'custom_field', 
+                   array('attr' => array('class' => 'cf-fields'), 'group' => $options['cFGroup']))
+           ;
+       }
+       
+       /**
+        * @param OptionsResolverInterface $resolver
+        */
+       public function setDefaultOptions(OptionsResolverInterface $resolver)
+       {
+           $resolver->setDefaults(array(
+               'data_class' => 'Chill\ReportBundle\Entity\Report'
+           ));
+
+           $resolver->setRequired(array(
+               'em',
+               'cFGroup',
+           ));
+
+           $resolver->setAllowedTypes(array(
+               'em' => 'Doctrine\Common\Persistence\ObjectManager',
+               'cFGroup' => 'Chill\CustomFieldsBundle\Entity\CustomFieldsGroup'
+           ));
+       }
+
+       /**
+        * @return string
+        */
+       public function getName()
+       {
+           return 'chill_reportbundle_report';
+       }
+   }
+
+### Available configuration
+
+Those options are available in the configuration, under the `chill_custom_field` key.
+
+Example :
+
+   chill_custom_field:
+      show_empty_values_in_views:  false
+
+show_empty_values_in_views *boolean*:
+   Allow to hide / show empty values in views. The aim of this configuration parameter is to hide (or show) empty values when :term:`custom fields group` are rendered.
+
+   Default value : `true`
+
+### Glossary
+
+   custom fields group
+      A group of custom fields

docs/source/bundles/event.md

@@ -0,0 +1,23 @@
+Permission is granted to copy, distribute and/or modify this document
+   under the terms of the GNU Free Documentation License, Version 1.3
+   or any later version published by the Free Software Foundation;
+   with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+   A copy of the license is included in the section entitled "GNU
+   Free Documentation License".
+
+# Event bundle
+
+## Template & Menu
+
+The event bundle has a special template with a specific menu for actions on
+events. This menu is called `event`.
+
+### ChillEventBundle::layout.html.twig
+
+This layout extends `ChillMainBundle::layoutWithVerticalMenu.html.twig` and add the menu `event`
+
+It proposes a new block :
+
+* event_content
+
+  * where to display content relative to the event.

docs/source/bundles/group.md

@@ -0,0 +1,34 @@
+Permission is granted to copy, distribute and/or modify this document
+   under the terms of the GNU Free Documentation License, Version 1.3
+   or any later version published by the Free Software Foundation;
+   with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+   A copy of the license is included in the section entitled "GNU
+   Free Documentation License".
+
+# Group bundle
+
+Allow to group people in a group. This group may be a family, an activity group, ...
+
+   :local:
+
+###### Entities
+
+###### Macros
+
+## Group sticker
+
+Macro file
+   `ChillGroupBundle:Group:macro.html.twig`
+Macro name
+   `_render`
+Macro envelope
+   `group`, instance of :class:`Chill\GroupBundle\Entity\CGroup`
+
+When to use this macro ?
+   When you want to represent group.
+Example usage :
+   ```jinja
+   {% import 'ChillGroupBundle:Group:macro.html.twig' as m %}
+
+   {{ m._render(g) }}
+   ```

docs/source/bundles/index.md

@@ -0,0 +1,23 @@
+Permission is granted to copy, distribute and/or modify this document
+   under the terms of the GNU Free Documentation License, Version 1.3
+   or any later version published by the Free Software Foundation;
+   with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+   A copy of the license is included in the section entitled "GNU
+   Free Documentation License".
+
+# Bundles documentation
+
+You will find here documentation about bundles working with Chill.
+
+- [Main bundle](main.md)
+- [Custom Fields bundle](custom-fields.md)
+- [Person bundle](person.md)
+- [Report bundle](report.md)
+- [Activity bundle](activity.md)
+- [Group bundle](group.md)
+- [Event bundle](event.md)
+- [Ldap bundle (synchronisation between ldap and database)](ldap.md)
+
+### Your bundle here ?
+
+The contributors still do not have a policy about those bundle integration, but we would like to be very open on this subject. Please write to us [or open an issue ](https://redmine.champs-libres.coop/projects/chill/issues).

docs/source/bundles/ldap.md

@@ -0,0 +1,159 @@
+Permission is granted to copy, distribute and/or modify this document
+   under the terms of the GNU Free Documentation License, Version 1.3
+   or any later version published by the Free Software Foundation;
+   with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+   A copy of the license is included in the section entitled "GNU
+   Free Documentation License".
+
+# LDAP bundle
+
+This bundle binds the database with an ldap directory.
+
+The bundle synchronize the ldap directory with users in the database. It also
+provides a way to check user credentials against the ldap directory.
+
+   :local:
+
+###### Current limitations
+
+- The length of the ldap dn must be < 255 characters
+- if the username extracted from the ldap is updated, the changes are not reflected in the database and remains the same
+
+###### Entities provided
+
+This bundle provides only one entity : :class:[Chill\\LdapBundle\\Entity\\UserLdapBinding`
+
+###### How the synchronizer works ?
+
+#. The synchronizer performs a query on `dn` and `query` defined in the [configuration ](configuration.md).
+#. For each entry returned by the query, it looks if the `dn` exists in the database
+
+   #. If the entry does not exists :
+
+      #. the synchronizer looks for user with same username as defined by `username_attr`, and bind it with the `dn` if it exists.
+      #. else, a user is created with username defined by `username_attr` (if the ldap contains more than one attribute, the first attribute returned is used)
+
+   #. if a user exists which is already binded with the `dn`, the entry is ignored.
+
+#. The synchronizer looks for dn existing in database and which were not returned by the query performed in 1.
+
+   #. If they exists, those user are set to `enabled=false`: they are not allowed to login.
+
+###### Installation
+
+This bundle requires :
+
+- PHP LDAP ext
+- `symfony/ldap` with minimal version 3.1. Note that, currently, Chill uses Symfony 2.8: you should add the dependency on this single package manually
+
+In your composer.json, for stable version :
+
+   "require": {
+           // .. other dependencies
+           "symfony/ldap" : "~3.1",
+           "chill-project/ldap": "~1.0"
+   }
+
+And for dev version :
+
+   "require": {
+           // .. other dependencies
+           "symfony/ldap" : "~3.1",
+           "chill-project/ldap": "dev-master@dev"
+   }
+
+###### Configuration
+
+## Configuration of the bundle
+
+   # Default configuration for extension with alias: "chill_ldap"
+   chill_ldap:
+       server:               # Required
+
+           # the host of the ldap directory
+           host:                 ~ # Required, Example: localhost
+
+           # the port to reach the ldap directory
+           port:                 389
+
+           # the version of the ldap directory
+           version:              3
+
+           # Is the use of ssl required to establish connection
+           use_ssl:              false
+
+           # Is the use of startssl required to establish connection
+           use_starttls:         false
+
+           # the user to bind to dn directory. Required for searching existing users.
+           bind_dn:              ~ # Required, Example: cn=user,dn=chill,dn=social
+
+           # the user's password to bind to dn directory.
+           bind_password:        ~ # Required, Example: paSSw0rD
+       user_query:           # Required
+
+           # The DN where the query is executed
+           dn:                   ~ # Example: ou=People,dc=champs-libres,dc=coop
+
+           # The query which will allow to retrieve users
+           query:                ~ # Example: (&(objectClass=inetOrgPerson)(userPassword=*))
+
+           # The attribute which will provide username (=login)
+           username_attr:        cn
+
+Example :
+
+   chill_ldap:
+       server:
+           # host, bind_dn and bind_password are imported from parameters.yml
+           host: "%ldap_host%"
+           bind_dn: "%ldap_bind_dn%"
+           bind_password: "%ldap_bind_password%"
+       user_query:
+           dn: dc=champs-libres,dc=coop
+           query: "(&(objectClass=inetOrgPerson)(userPassword=*))"
+
+## Configuration of the security part of chill
+
+Simply add the following config in the firewall of the security bundle :
+`chill_ldap_form_login: ~`. This config is located in `app/config/security.yml`
+
+Example of a configuration :
+
+   # in app/config/security.yml
+
+       firewalls:
+           dev:
+               pattern: ^/(_(profiler|wdt)|css|images|js)/
+               security: false
+
+           default:
+               anonymous: ~
+               # enable the login check by a form, agaisnt the database
+               form_login:
+                   csrf_parameter: _csrf_token
+                   csrf_token_id: authenticate
+                   csrf_provider: form.csrf_provider
+               # enable the login check by a form, against the ldap
+               chill_ldap_form_login: ~ # this is the line you should add
+
+Note that, if you enable the login check by form **and** by the ldap,
+the password will be checked against the database **and** against the ldap.
+If one of them match, the login will succeed.
+
+If you want to completely disable login check against the database,
+simply remove the `form_login` entry and all his options.
+
+## Command and crontab
+
+Synchronize the database :
+
+   php app/console chill:ldap:synchronize
+
+For getting more debug message :
+
+   php app/console chill:ldap:synchronize -vvv
+
+You should run this command regularly (using crontab or
+`systemd timer ](https://www.freedesktop.org/software/systemd/man/systemd.timer.html#))
+to synchronize ldap and database automatically.

docs/source/bundles/main.md

@@ -0,0 +1,38 @@
+Permission is granted to copy, distribute and/or modify this document
+   under the terms of the GNU Free Documentation License, Version 1.3
+   or any later version published by the Free Software Foundation;
+   with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+   A copy of the license is included in the section entitled "GNU
+   Free Documentation License".
+
+
+# Main bundle
+
+This bundle is **required** for running Chill.
+
+This bundle provide :
+
+* Access control model (users, groups, and all concepts)
+* ...
+
+   this section is incomplete.
+
+###### Macros
+
+## Address sticker
+
+Macro file
+   `ChillMainBundle:Address:macro.html.twig`
+Macro name
+   `_render`
+Macro envelope
+   `address`, instance of :class:`Chill\MainBundle\Entity\Address`
+
+When to use this macro ?
+   When you want to represent an address.
+Example usage :
+   ```jinja
+   {% import 'ChillMainBundle:Address:macro.html.twig' as m %}
+
+   {{ m._render(address) }}
+   ```

docs/source/bundles/person.md

@@ -0,0 +1,196 @@
+Permission is granted to copy, distribute and/or modify this document
+   under the terms of the GNU Free Documentation License, Version 1.3
+   or any later version published by the Free Software Foundation;
+   with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+   A copy of the license is included in the section entitled "GNU
+   Free Documentation License".
+
+# Person bundle
+
+This bundle provides the ability to record people in the software. This bundle is required by other bundle.
+
+   :local:
+
+###### Entities provided
+
+   describe entities provided by person bundle
+
+
+###### Search terms
+
+The class [Chill\PersonBundle\Search\PersonSearch` provide the search module.
+
+## Domain
+
+The search upon "person" is provided by default. The `@person` domain search may be omitted.
+
+* `@person` is the domain search for people.
+
+## Arguments
+
+* `firstname` : provide the search on firstname. Example : `firstname:Depardieu`. May match part of the firstname (`firsname:dep` will match Depardieu)
+* `lastname` : provide the search on lastname. May match part of the lastname.
+* `birthdate` : provide the search on the birthdate. Example : `birthdate:1996-01-19`
+* `gender`: performs search on man/woman. The accepted values are `man` or `woman`.
+* `nationality` : performs search on nationality. Value must be a country code `as described in ISO 3166 ](http://www.iso.org/iso/fr/home/standards/country_codes.htm). Example : [nationality:FR`.
+
+## Default
+
+The default search is performed on firstname and/or lastname. Both are concatened before search. If values are separated by spaces, the clause `AND` is used : the search `dep ge` will match 'Gérard Depardieu` or 'Jean Depagelles', but not 'Charline Depardieu' (missing 'Ge' in word).
+
+###### Configuration options
+
+Those options are available under `chill_person` key.
+
+Example of configuration:
+
+   chill_person:
+      validation:
+         birthdate_not_after: P15Y
+      person_fields:
+         # note: visible is the default config. This key may be omitted if visible is chosen.
+         nationality: hidden
+         email: hidden
+         place_of_birth: visible
+         phonenumber: hidden
+         country_of_birth: hidden
+         marital_status: visible
+         spoken_languages: hidden
+         address: visible
+
+birthdate_not_after *string*
+   The period duration before today during which encoding birthdate is not possible. The period is a string matching the format of `ISO_8601`, which is also use to build `DateInterval classes ](http://php.net/manual/en/dateinterval.construct.php).
+
+   Example: [P1D`, `P18Y`
+
+   Default value: `P1D` which means that birthdate before the current day (= yesterday) are allowed.
+
+person_fields *array*
+   This define the visibility of some fields. By default, all fields are visible, but you can choose to hide some of them. Available keys are :
+
+   * `nationality`
+   * `country_of_birth`
+   * `place_of_birth`
+   * `phonenumber`
+   * `email`
+   * `marital_status`
+   * `spoken_languages`
+   * `address`
+
+   Possibles values: `hidden` or `visible` (all other value will raise an Exception).
+
+   Default value : `visible`, which means that all fields are visible.
+
+   Example:
+
+   ```yaml
+      chill_person:
+         person_fields:
+            nationality: hidden
+            email: hidden
+            phonenumber: hidden
+```
+
+   If all the field of a "box" are hidden, the whole box does not appears. Example: if the fields `phonenumber` and `email` are hidden, the title `Contact information` will be hidden in the UI.
+
+   If you hide multiple fields, for a better integration you may want to override the template, for a better appeareance. See `the symfony documentation ](http://symfony.com/doc/current/book/templating.html#overriding-bundle-templates) about this feature.
+
+###### Macros
+
+## Sticker for a person
+
+Macro file
+   `ChillPersonBundle:Person:macro.html.twig`
+Macro envelope
+   `render(p, withLink=false)`
+
+   `p` is an instance of :class:`Chill\PersonBundle\Entity\Person`
+
+   `withLink` :class:`boolean`
+When to use this macro ?
+   When you want to represent a person.
+Example usage :
+   ```jinja
+   {% import "ChillPersonBundle:Person:macro.html.twig" as person_ %}
+
+   {{ person_.render(person, true) }}
+   ```
+
+###### Layout events and delegated blocks
+
+## `chill_block.person_post_vertical_menu` event
+
+This event is available to add content below of the vertical menu (on the right).
+
+The context is :
+
+- `person` : the current person which is rendered. Instance of :class:`Chill\PersonBundle\Entity\Person`
+
+###### Widgets
+
+## Add a list of person on homepage
+
+The bundle provide a way to add a list of accompanyied person on the homepage:
+
+   chill_main:
+       widgets:
+           homepage:
+               -
+                   order: 10
+                   widget_alias: person_list
+                   person_list:
+                       # customize the number of items
+                       number_of_items: 20
+
+                       # only active
+                       only_active: true
+
+                       # you can add some filtering class, which will implements
+                       # Chill\PersonBundle\PersonListWidget\PersonFilteringInterface
+                       filtering_class: "\Hepc\HomepagePersonFiltering"
+
+                       # when the view is overriden, you can add some custom fields
+                       # to the view
+                       custom_fields: [school-2fb5440e-192c-11e6-b2fd-74d02b0c9b55]
+
+###### Commands
+
+## `chill:person:move`
+
+	Usage:
+		chill:person:move [options]
+
+	Options:
+		-f, --from=FROM       The person id to delete, all associated data will be moved before
+		-t, --to=TO           The person id which will received data
+				--dump-sql        dump sql to stdout
+				--force           execute sql instead of dumping it
+		-h, --help            Display this help message
+		-q, --quiet           Do not output any message
+		-V, --version         Display this application version
+				--ansi            Force ANSI output
+				--no-ansi         Disable ANSI output
+		-n, --no-interaction  Do not ask any interactive question
+		-e, --env=ENV         The Environment name. [default: "dev"]
+				--no-debug        Switches off debug mode.
+		-v|vv|vvv, --verbose  Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
+
+	Help:
+		Move all the associated entities on a "from" person to a "to" person and remove the old person
+
+Move all the entities associated to a person onto another one, and remove the old person.
+
+  Some entities are ignored and will be deleted:
+
+  - the accompanying periods ;
+  - the data attached to a person entity: name, address, date of birth, etc. Thos should be merge before the move.
+
+It is advised to run first the command with the `dump-sql` option and, then, use the `force` option.
+
+The moving and suppression is executed inside a transaction, ensuring no data loss if the migration fails.
+
+  Using bash and awk, it is easy to use a TSV file (values separated by a tab, not a comma) to create move commands. Assuming our file is named `twins.tsv` and contains two columns: the first one with `from` ids, and the second one with `to` ids:
+
+  ```bash
+    awk '{ print "php app/console chill:person:move --dump-sql --from " $1 " --to " $2;}' twins.tsv
+```

docs/source/bundles/report.md

@@ -0,0 +1,32 @@
+Permission is granted to copy, distribute and/or modify this document
+   under the terms of the GNU Free Documentation License, Version 1.3
+   or any later version published by the Free Software Foundation;
+   with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+   A copy of the license is included in the section entitled "GNU
+   Free Documentation License".
+
+# Report bundle
+
+This bundle provides the ability to record report about people. We use custom fields to let user add fields to reports.
+
+   :local:
+
+   The documentation about report is not writtend
+
+## Concepts
+
+## Search
+
+### Domain
+
+* `@report` is the domain search for reports.
+
+### Arguments
+
+* `date` : The date of the report
+
+### Default
+
+The report's date is the default value. 
+
+An error is thrown if an argument `date` and a default is used.

docs/source/bundles/rst/activity.rst

@@ -35,12 +35,12 @@ Example of configuration:
 
    chill_activity:
       form:
-         time_duration: 
+         time_duration:
             - { label: '12 minutes', seconds: 720 }
             - { label: '30 minutes', seconds: 1800 }
 
 form.time_duration *array*
-   The duration which might be suggested when the user create or update an activity. The value must be an array of object, where each object must have a :code:`label` and a :code:`seconds` key. The label provide which is shown to user (the label will be translated, if possible) and the seconds the duration.
+   The duration which might be suggested when the user create or update an activity. The value must be an array of object, where each object must have a `label` and a `seconds` key. The label provide which is shown to user (the label will be translated, if possible) and the seconds the duration.
 
    Example: see the example above
 
@@ -57,9 +57,9 @@ Activity reason sticker
 Macro file
    `ChillActivityBundle:ActivityReason:macro.html.twig`
 Macro envelope
-   :code:`reason(r)`
+   `reason(r)`
 
-   :code:`p` is an instance of :class:`Chill\ActivityBundle\Entity\ActivityReason`
+   `p` is an instance of :class:`Chill\ActivityBundle\Entity\ActivityReason`
 
 When to use this macro ?
    When you want to represent an activity reason.

docs/source/bundles/rst/group.rst

@@ -33,9 +33,9 @@ Group sticker
 Macro file
    `ChillGroupBundle:Group:macro.html.twig`
 Macro name
-   :code:`_render`
+   `_render`
 Macro envelope
-   :code:`group`, instance of :class:`Chill\GroupBundle\Entity\CGroup`
+   `group`, instance of :class:`Chill\GroupBundle\Entity\CGroup`
 
 When to use this macro ?
    When you want to represent group.

docs/source/bundles/rst/ldap.rst

@@ -35,34 +35,34 @@ This bundle provides only one entity : :class:`Chill\\LdapBundle\\Entity\\UserLd
 How the synchronizer works ?
 ****************************
 
-#. The synchronizer performs a query on :code:`dn` and :code:`query` defined in the :ref:`configuration <configuration>`.
-#. For each entry returned by the query, it looks if the :code:`dn` exists in the database
+#. The synchronizer performs a query on `dn` and `query` defined in the :ref:`configuration <configuration>`.
+#. For each entry returned by the query, it looks if the `dn` exists in the database
 
    #. If the entry does not exists :
 
-      #. the synchronizer looks for user with same username as defined by :code:`username_attr`, and bind it with the :code:`dn` if it exists.
-      #. else, a user is created with username defined by :code:`username_attr` (if the ldap contains more than one attribute, the first attribute returned is used)
+      #. the synchronizer looks for user with same username as defined by `username_attr`, and bind it with the `dn` if it exists.
+      #. else, a user is created with username defined by `username_attr` (if the ldap contains more than one attribute, the first attribute returned is used)
 
-   #. if a user exists which is already binded with the :code:`dn`, the entry is ignored.
+   #. if a user exists which is already binded with the `dn`, the entry is ignored.
 
-#. The synchronizer looks for dn existing in database and which were not returned by the query performed in 1. 
+#. The synchronizer looks for dn existing in database and which were not returned by the query performed in 1.
 
-   #. If they exists, those user are set to :code:`enabled=false`: they are not allowed to login.
+   #. If they exists, those user are set to `enabled=false`: they are not allowed to login.
 
 Installation
 ************
 
-This bundle requires : 
+This bundle requires :
 
 - PHP LDAP ext
-- :code:`symfony/ldap` with minimal version 3.1. Note that, currently, Chill uses Symfony 2.8: you should add the dependency on this single package manually
+- `symfony/ldap` with minimal version 3.1. Note that, currently, Chill uses Symfony 2.8: you should add the dependency on this single package manually
 
-In your composer.json, for stable version : 
+In your composer.json, for stable version :
 
 .. code-block:: json
 
    "require": {
-           // .. other dependencies 
+           // .. other dependencies
            "symfony/ldap" : "~3.1",
            "chill-project/ldap": "~1.0"
    }
@@ -74,7 +74,7 @@ And for dev version :
 .. code-block:: json
 
    "require": {
-           // .. other dependencies 
+           // .. other dependencies
            "symfony/ldap" : "~3.1",
            "chill-project/ldap": "dev-master@dev"
    }
@@ -126,7 +126,7 @@ Configuration of the bundle
            username_attr:        cn
 
 
-Example : 
+Example :
 
 .. code-block:: yaml
 
@@ -147,7 +147,7 @@ Configuration of the security part of chill
 Simply add the following config in the firewall of the security bundle :
 `chill_ldap_form_login: ~`. This config is located in `app/config/security.yml`
 
-Example of a configuration : 
+Example of a configuration :
 
 .. code-block:: yaml
 
@@ -169,26 +169,26 @@ Example of a configuration :
                chill_ldap_form_login: ~ # this is the line you should add
 
 
-Note that, if you enable the login check by form **and** by the ldap, 
+Note that, if you enable the login check by form **and** by the ldap,
 the password will be checked against the database **and** against the ldap.
 If one of them match, the login will succeed.
 
-If you want to completely disable login check against the database, 
-simply remove the :code:`form_login` entry and all his options.
+If you want to completely disable login check against the database,
+simply remove the `form_login` entry and all his options.
 
 .. _command-and-crontab:
 
 Command and crontab
 ===================
 
-Synchronize the database : 
+Synchronize the database :
 
 .. code-block:: bash
 
    php app/console chill:ldap:synchronize
 
 
-For getting more debug message : 
+For getting more debug message :
 
 .. code-block:: bash
 
@@ -196,7 +196,7 @@ For getting more debug message :
 
 
 
-You should run this command regularly (using crontab or 
+You should run this command regularly (using crontab or
 `systemd timer <https://www.freedesktop.org/software/systemd/man/systemd.timer.html#>`_)
 to synchronize ldap and database automatically.
 

docs/source/bundles/rst/main.rst

@@ -7,7 +7,7 @@
    Free Documentation License".
 
 .. _main-bundle:
- 
+
 Main bundle
 ###########
 
@@ -34,9 +34,9 @@ Address sticker
 Macro file
    `ChillMainBundle:Address:macro.html.twig`
 Macro name
-   :code:`_render`
+   `_render`
 Macro envelope
-   :code:`address`, instance of :class:`Chill\MainBundle\Entity\Address`
+   `address`, instance of :class:`Chill\MainBundle\Entity\Address`
 
 When to use this macro ?
    When you want to represent an address.

docs/source/bundles/rst/person.rst

@@ -22,8 +22,8 @@ Entities provided
 .. todo::
 
    describe entities provided by person bundle
-   
-   
+
+
 Search terms
 ************
 
@@ -82,8 +82,8 @@ birthdate_not_after *string*
    Default value: `P1D` which means that birthdate before the current day (= yesterday) are allowed.
 
 person_fields *array*
-   This define the visibility of some fields. By default, all fields are visible, but you can choose to hide some of them. Available keys are : 
-   
+   This define the visibility of some fields. By default, all fields are visible, but you can choose to hide some of them. Available keys are :
+
    * `nationality`
    * `country_of_birth`
    * `place_of_birth`
@@ -97,7 +97,7 @@ person_fields *array*
 
    Default value : `visible`, which means that all fields are visible.
 
-   Example: 
+   Example:
 
    .. code-block:: yaml
 
@@ -107,10 +107,10 @@ person_fields *array*
             email: hidden
             phonenumber: hidden
 
-.. note:: 
+.. note::
    If all the field of a "box" are hidden, the whole box does not appears. Example: if the fields `phonenumber` and `email` are hidden, the title `Contact information` will be hidden in the UI.
 
-.. note:: 
+.. note::
    If you hide multiple fields, for a better integration you may want to override the template, for a better appeareance. See `the symfony documentation <http://symfony.com/doc/current/book/templating.html#overriding-bundle-templates>`_ about this feature.
 
 .. _person-bundle-macros:
@@ -124,11 +124,11 @@ Sticker for a person
 Macro file
    `ChillPersonBundle:Person:macro.html.twig`
 Macro envelope
-   :code:`render(p, withLink=false)`
+   `render(p, withLink=false)`
 
-   :code:`p` is an instance of :class:`Chill\PersonBundle\Entity\Person`
+   `p` is an instance of :class:`Chill\PersonBundle\Entity\Person`
 
-   :code:`withLink` :class:`boolean`
+   `withLink` :class:`boolean`
 When to use this macro ?
    When you want to represent a person.
 Example usage :
@@ -141,14 +141,14 @@ Example usage :
 Layout events and delegated blocks
 ***********************************
 
-:code:`chill_block.person_post_vertical_menu` event
+`chill_block.person_post_vertical_menu` event
 ====================================================
 
 This event is available to add content below of the vertical menu (on the right).
 
-The context is : 
+The context is :
 
-- :code:`person` : the current person which is rendered. Instance of :class:`Chill\PersonBundle\Entity\Person`
+- `person` : the current person which is rendered. Instance of :class:`Chill\PersonBundle\Entity\Person`
 
 Widgets
 *******
@@ -162,8 +162,8 @@ The bundle provide a way to add a list of accompanyied person on the homepage:
 
    chill_main:
        widgets:
-           homepage: 
-               - 
+           homepage:
+               -
                    order: 10
                    widget_alias: person_list
                    person_list:
@@ -180,12 +180,12 @@ The bundle provide a way to add a list of accompanyied person on the homepage:
                        # when the view is overriden, you can add some custom fields
                        # to the view
                        custom_fields: [school-2fb5440e-192c-11e6-b2fd-74d02b0c9b55]
-  
+
 Commands
 ********
 
 
-:code:`chill:person:move`
+`chill:person:move`
 =========================
 
 .. code-block:: txt
@@ -213,21 +213,21 @@ Commands
 
 Move all the entities associated to a person onto another one, and remove the old person.
 
-.. warning:: 
+.. warning::
 
-  Some entities are ignored and will be deleted: 
+  Some entities are ignored and will be deleted:
 
   - the accompanying periods ;
   - the data attached to a person entity: name, address, date of birth, etc. Thos should be merge before the move.
 
-It is advised to run first the command with the :code:`dump-sql` option and, then, use the :code:`force` option.
+It is advised to run first the command with the `dump-sql` option and, then, use the `force` option.
 
 The moving and suppression is executed inside a transaction, ensuring no data loss if the migration fails.
 
 .. note::
 
-  Using bash and awk, it is easy to use a TSV file (values separated by a tab, not a comma) to create move commands. Assuming our file is named :code:`twins.tsv` and contains two columns: the first one with :code:`from` ids, and the second one with :code:`to` ids: 
+  Using bash and awk, it is easy to use a TSV file (values separated by a tab, not a comma) to create move commands. Assuming our file is named `twins.tsv` and contains two columns: the first one with `from` ids, and the second one with `to` ids:
 
   .. code-block:: bash
 
-    awk '{ print "php app/console chill:person:move --dump-sql --from " $1 " --to " $2;}' twins.tsv 
+    awk '{ print "php app/console chill:person:move --dump-sql --from " $1 " --to " $2;}' twins.tsv

docs/source/development/FAQ.md

@@ -0,0 +1,23 @@
+# Frequently asked questions
+
+## Continuous integration
+
+Pipeline fails, but php-cs-fixer doesn't alert me when running it locally?
+========================================
+
+It is possible that you run php-cs-fixer on your local instance of chill and no fixes are made.
+Everything seems fine, so you push. However, once the pipeline is run in gitlab, you're notified that it failed due to php
+cs errors.
+
+In this case it's likely that you have to update your version of php-cs-fixer.
+php-cs-fixer is installed when building the docker image: https://gitea.champs-libres.be/Chill-project/chill-skeleton-basic/src/branch/main/Dockerfile#L50
+
+Consequently, to update php-cs-fixer, we have to update the image by building it again.
+
+For this the following commands can be used.
+
+```
+    docker compose build --pull php
+    # replace existing containers
+    docker compose up -d --force-recreate php
+```

docs/source/development/FAQ.rst

@@ -1,36 +0,0 @@
-.. Copyright (C)  2014 Champs Libres Cooperative SCRLFS
-Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.3
-or any later version published by the Free Software Foundation;
-with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
-A copy of the license is included in the section entitled "GNU
-Free Documentation License".
-
-.. _faq:
-
-
-Frequently asked questions
-####################
-
-Continuous integration
-***********
-
-Pipeline fails, but php-cs-fixer doesn't alert me when running it locally ?
-========================================
-
-It is possible that you run php-cs-fixer on your local instance of chill and no fixes are made.
-Everything seems fine, so you push. However once the pipeline is run in gitlab, you're notified that it failed due to php
-cs errors.
-
-In this case it's likely that you have to update your version of php-cs-fixer.
-php-cs-fixer is installed when building the docker image: https://gitea.champs-libres.be/Chill-project/chill-skeleton-basic/src/branch/main/Dockerfile#L50
-
-Consequently, to update php-cs-fixer we have to update the image by building it again.
-
-For this the following commands can be used,
-
-.. code-block:: php
-
-    docker compose build --pull php
-    # replace existing containers
-    docker compose up -d --force-recreate php

docs/source/development/access_control_model.md

@@ -1,19 +1,15 @@
-.. Copyright (C)  2015 Champs Libres Cooperative SCRLFS
-   Permission is granted to copy, distribute and/or modify this document
+Permission is granted to copy, distribute and/or modify this document
    under the terms of the GNU Free Documentation License, Version 1.3
    or any later version published by the Free Software Foundation;
    with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
    A copy of the license is included in the section entitled "GNU
    Free Documentation License".
 
-Access controle model
-**********************
+###### Access controle model
 
-.. contents:: Table of content
     :local:
 
-Concepts
-========
+## Concepts
 
 Every time an entity is created, viewed or updated, the software check if the user has the permission to make this action. The decision is made with three parameters :
 
@@ -23,20 +19,15 @@ Every time an entity is created, viewed or updated, the software check if the us
 
 The user must be granted access to the action on this particular entity, with this scope and center.
 
-TL;DR
-=====
+## TL;DR
 
-Resolve scope and center
-------------------------
+### Resolve scope and center
 
 In a service, resolve the center and scope of an entity
 
-.. code-block:: php
-
    use Chill\MainBundle\Security\Resolver\CenterResolverDispatcher;
    use Chill\MainBundle\Security\Resolver\ScopeResolverDispatcher;
 
-
    class MyService {
       private ScopeResolverDispatcher $scopeResolverDispatcher;
       private CenterResolverDispatcher $centerResolverDispatcher;
@@ -58,8 +49,6 @@ In a service, resolve the center and scope of an entity
 
 In twig template, resolve the center:
 
-.. code-block:: twig
-
    {# resolve a center #}
 
    {% if person|chill_resolve_center is not null%}
@@ -81,8 +70,6 @@ In twig template, resolve the center:
 
 In twig template, resolve the scope:
 
-.. code-block:: twig
-
    {% if entity|chill_is_scope_concerned %}
 
       {% if entity|chill_resolve_scope is iterable %}
@@ -98,10 +85,7 @@ In twig template, resolve the scope:
       {% endfor %}
    {%- endif -%}
 
-Build a ``Voter``
------------------
-
-.. code-block:: php
+### Build a ``Voter``
 
    <?php
 
@@ -151,7 +135,6 @@ Build a ``Voter``
                ->build();
        }
 
-
        protected function supports($attribute, $subject)
        {
            return $this->voterHelper->supports($attribute, $subject);
@@ -194,25 +177,19 @@ Build a ``Voter``
            return array();
        }
 
-
        public function getRolesWithHierarchy()
        {
            return ['PersonDocument' => $this->getRoles() ];
        }
    }
 
-
-
-
-From an user point of view
-==========================
+## From an user point of view
 
 The software is design to allow fine tuned access rights for complicated installation and team structure. The administrators may also decide that every user has the right to see all resources, where team have a more simple structure. 
 
 Here is an overview of the model.
 
-Chill can be multi-center
--------------------------
+### Chill can be multi-center
 
 Chill is designed to be installed once for social center who work with multiple teams separated, or for social services's federation who would like to share the same installation of the software for all their members. 
 
@@ -222,8 +199,7 @@ Otherwise, it is not required to create multiple center: Chill can also work for
 
 Obviously, users working in the different centers are not allowed to see the entities (_persons_, _reports_, _activities_) of other centers. But users may be attached to multiple centers: consequently they will be able to see the entities of the multiple centers they are attached to.
 
-Inside center, scope divide team
---------------------------------
+### Inside center, scope divide team
 
 Users are attached to one or more center and, inside to those center, there may exists differents scopes. The aim of those _scopes_ is to divide the whole team of social worker amongst different departement, for instance: the social team, the psychologist team, the nurse team, the administrative team, ... Each team is granted of different rights amongst scope. For instance, the social team may not see the _activities_ of the psychologist team. The administrative team may see the date & time's activities, but is not allowed to see the detail of those entities (the personal notes, ...).
 
@@ -233,9 +209,7 @@ As entities have only one scopes, if some entities must be shared across two dif
 
 Example: if some activities must be seen and updated between nurses and psychologists, the administrator will create a scope "nurse and psy" and add the ability for both team "nurse" and "psychologist" to "create", "see", and "update" the activities belonging to scope "nurse and psy".
 
-
-Where does the ``scope`` and ``center`` comes from ?
-====================================================
+## Where does the [`scope`` and ``center`` comes from ?
 
 Most often, scope and center comes from user's input:
 
@@ -256,30 +230,23 @@ But sometimes, this implementation does not fits the needs:
 
 For this reasons, associated center and scopes must be resolved programmatically. The default implementation rely on the model association, as described above. But it becomes possible to change the behaviour on different implementations.
 
-Is my entity "concerned" by scopes ?
-------------------------------------
+### Is my entity "concerned" by scopes ?
 
 Some entities are concerned by scope, some not.
 
 This is also programmatically resolved.
 
-The concepts translated into code
-===================================
+## The concepts translated into code
 
-.. figure:: /_static/access_control_model.png
    
    Schema of the access control model
 
 Chill handle **entities**, like *persons*, *reports* (associated to *persons*), *activities* (also associated to *_persons*), ... On creation, those entities are linked to one center and, eventually, to one scope. They implements the interface `HasCenterInterface`.
 
-.. note::
-
    Somes entities are linked to a center through the entity they are associated with. For instance, *activities* or *reports* are associated to a *person*, and the person is associated to a *center*. The *report*'s *center* is always the *person*'s *center*.
 
 Entities may be associated with a scope. In this case, they implement the `HasScopeInterface`.
 
-.. note::
-
    Currently, only the *person* entity is not associated with a scope. 
 
 At each step of his lifetime (creation, view of the entity and eventually of his details, update and, eventually, deletion), the right of the user are checked. To decide wether the user is granted right to execute the action, the software must decide with those elements :
@@ -291,13 +258,10 @@ At each step of his lifetime (creation, view of the entity and eventually of his
 
 All those action are executed through symfony voters and helpers. 
 
-How to check authorization ?
-============================
+## How to check authorization ?
 
 Just use the symfony way-of-doing, but do not forget to associate the entity you want to check access. For instance, in controller :  
 
-.. code-block:: php
-
    class MyController extends Controller 
    {
 
@@ -311,12 +275,9 @@ Just use the symfony way-of-doing, but do not forget to associate the entity you
 
 And in template :
 
-.. code-block:: twig
-
    {{ if is_granted('CHILL_ENTITY_SEE', entity) %}print something{% endif %}
 
-Retrieving reachable scopes and centers for a user
---------------------------------------------------
+### Retrieving reachable scopes and centers for a user
 
 The class :class:`Chill\\MainBundle\\Security\\Authorization\\AuthorizationHelperInterface` helps you to get centers and scope reachable by a user.
 
@@ -325,9 +286,7 @@ Those methods are intentionnaly build to give information about user rights:
 - getReachableCenters: to get reachable centers for a user
 - getReachableScopes : to get reachable scopes for a user
 
-
-Adding your own roles
----------------------
+### Adding your own roles
 
 Extending Chill will requires you to define your own roles and rules for your entities. You will have to define your own voter to do so.
 
@@ -336,28 +295,20 @@ To create your own roles, you should:
 * implement your own voter. This voter will have to extends the :class:`Chill\\MainBundle\\Security\\AbstractChillVoter`. As defined by Symfony, this voter must be declared as a service and tagged with `security.voter`;
 * declare the role through implementing a service tagged with `chill.role` and implementing :class:`Chill\\MainBundle\\Security\\ProvideRoleInterface`.
 
-.. note::
-
    Both operation may be done through a simple class: you can implements :class:`Chill\\MainBundle\\Security\\ProvideRoleInterface` and :class:`Chill\\MainBundle\\Security\\AbstractChillVoter` on the same class. See live example: :class:`Chill\\ActivityBundle\\Security\\Authorization\\ActivityVoter`, and similar examples in the `PersonBundle` and `ReportBundle`.
 
-.. seealso::
-
-   `How to Use Voters to Check User Permissions <http://symfony.com/doc/current/cookbook/security/voters_data_permission.html>`_
+   `How to Use Voters to Check User Permissions ](http://symfony.com/doc/current/cookbook/security/voters_data_permission.html)
 
    From the symfony cookbook
 
-   `New in Symfony 2.6: Simpler Security Voters <http://symfony.com/blog/new-in-symfony-2-6-simpler-security-voters>`_
+   [New in Symfony 2.6: Simpler Security Voters ](http://symfony.com/blog/new-in-symfony-2-6-simpler-security-voters)
 
    From the symfony blog
 
-
-Declare your role
-^^^^^^^^^^^^^^^^^^
+##### Declare your role
 
 To declare new role, implement the class :class:`Chill\\MainBundle\\Security\\ProvideRoleInterface`. 
 
-.. code-block:: php
-
    interface ProvideRoleInterface
    {
        /**
@@ -375,21 +326,15 @@ To declare new role, implement the class :class:`Chill\\MainBundle\\Security\\Pr
        public function getRolesWithoutScope();
    }
 
-
 Then declare your service with a tag `chill.role`. Example : 
 
-.. code-block:: yaml
-
        your_service:
            class: Chill\YourBundle\Security\Authorization\YourVoter
            tags:
                - { name: chill.role }
 
-
 Example of an implementation of :class:`Chill\\MainBundle\\Security\\ProvideRoleInterface`:
 
-.. code-block:: php
-
    namespace Chill\PersonBundle\Security\Authorization;
 
    use Chill\MainBundle\Security\ProvideRoleInterface;
@@ -412,13 +357,10 @@ Example of an implementation of :class:`Chill\\MainBundle\\Security\\ProvideRole
 
    }
 
-Adding role hierarchy
-^^^^^^^^^^^^^^^^^^^^^
+##### Adding role hierarchy
 
 You should prepend Symfony's security component directly from your code. 
 
-.. code-block:: php
-
    namespace Chill\ReportBundle\DependencyInjection;
    use Symfony\Component\DependencyInjection\ContainerBuilder;
    use Symfony\Component\Config\FileLocator;
@@ -450,10 +392,7 @@ You should prepend Symfony's security component directly from your code.
        }
    }
 
-
-
-Implement your voter
-^^^^^^^^^^^^^^^^^^^^
+##### Implement your voter
 
 Most of the time, Voter will check that:
 
@@ -464,7 +403,6 @@ Most of the time, Voter will check that:
 
 Thats what we call the "autorization logic". But this logic may be replace by a new one, and developers should take care of it.
 
-
 Then voter implementation should take care of:
 
 * check the access to associated entities. For instance, if an ``Activity`` is associated to a ``Person``, the voter should first check that the user can show the associated ``Person``;
@@ -472,9 +410,6 @@ Then voter implementation should take care of:
 
 This is an example of implementation:
 
-
-.. code-block:: php
-
    <?php
 
    namespace Chill\DocStoreBundle\Security\Authorization;
@@ -513,7 +448,6 @@ This is an example of implementation:
                ->build();
        }
 
-
        protected function supports($attribute, $subject)
        {
            return $this->voterHelper->supports($attribute, $subject);
@@ -553,7 +487,6 @@ This is an example of implementation:
            // ...
        }
 
-
        public function getRolesWithHierarchy()
        {
            // ...
@@ -562,8 +495,6 @@ This is an example of implementation:
 
 Then, you will have to declare the service and tag it as a voter :
 
-.. code-block:: yaml
-
    services:
        chill.report.security.authorization.report_voter:
            class: Chill\ReportBundle\Security\Authorization\ReportVoter
@@ -572,18 +503,13 @@ Then, you will have to declare the service and tag it as a voter :
            tags:
             - { name: security.voter }
 
-
-How to resolve scope and center programmatically ?
-==================================================
+## How to resolve scope and center programmatically ?
 
 In a service, resolve the center and scope of an entity
 
-.. code-block:: php
-
    use Chill\MainBundle\Security\Resolver\CenterResolverDispatcher;
    use Chill\MainBundle\Security\Resolver\ScopeResolverDispatcher;
 
-
    class MyService {
       private ScopeResolverDispatcher $scopeResolverDispatcher;
       private CenterResolverDispatcher $centerResolverDispatcher;
@@ -605,8 +531,6 @@ In a service, resolve the center and scope of an entity
 
 In twig template, resolve the center:
 
-.. code-block:: twig
-
    {# resolve a center #}
 
    {% if person|chill_resolve_center is not null%}
@@ -628,8 +552,6 @@ In twig template, resolve the center:
 
 In twig template, resolve the scope:
 
-.. code-block:: twig
-
    {% if entity|chill_is_scope_concerned %}
 
       {% if entity|chill_resolve_scope is iterable %}
@@ -645,8 +567,7 @@ In twig template, resolve the scope:
       {% endfor %}
    {%- endif -%}
 
-What is the default implementation of Scope and Center resolver ?
------------------------------------------------------------------
+### What is the default implementation of Scope and Center resolver ?
 
 By default, the implementation rely on association into entities.
 
@@ -657,16 +578,14 @@ By default, the implementation rely on association into entities.
 
 Then, the default implementation will resolve the center and scope based on the implementation in your model.
 
-How to change the default behaviour ?
--------------------------------------
+### How to change the default behaviour ?
 
 Implements those interface into services:
 
 * ``Chill\MainBundle\Security\Resolver\CenterResolverInterface``;
 * ``Chill\MainBundle\Security\Resolver\ScopeResolverInterface``;
 
-Authorization into lists and index pages
-========================================
+## Authorization into lists and index pages
 
 Due to the fact that authorization model may be overriden, "list" and "index" pages should not rely on center and scope from controller. This must be delegated to dedicated service, which will be aware of the authorization model. We call them ``ACLAwareRepository``. This service must implements an interface, in order to allow to change the implementation.
 
@@ -674,14 +593,11 @@ The controller **must not** performs any DQL or SQL query.
 
 Example in a controller:
 
-.. code-block:: php
-
    namespace Chill\TaskBundle\Controller;
 
    use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
    use Chill\TaskBundle\Repository\SingleTaskAclAwareRepositoryInterface;
 
-
    final class SingleTaskController extends AbstractController
    {
 
@@ -729,11 +645,9 @@ Example in a controller:
        }
    }
 
-Writing ``ACLAwareRepository``
-------------------------------
+### Writing ``ACLAwareRepository``
 
-The ACLAwareRepository should rely on interfaces
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+##### The ACLAwareRepository should rely on interfaces
 
 As described above, the ACLAwareRepository will perform the query for listing entities, and take care of authorization.
 
@@ -743,9 +657,6 @@ The service must rely on this interface, and not on the default implementation.
 
 Example: at first, we design an interface for listing ``SingleTask`` entities: 
 
-
-.. code-block:: php
-
    <?php
 
    namespace Chill\TaskBundle\Repository;
@@ -782,8 +693,6 @@ Example: at first, we design an interface for listing ``SingleTask`` entities:
 
 Implements this interface and register the interface as an alias for the implementation.
 
-.. code-block:: yaml
-
    services:
        Chill\TaskBundle\Repository\SingleTaskAclAwareRepository:
            autowire: true
@@ -791,8 +700,7 @@ Implements this interface and register the interface as an alias for the impleme
 
        Chill\TaskBundle\Repository\SingleTaskAclAwareRepositoryInterface: '@Chill\TaskBundle\Repository\SingleTaskAclAwareRepository'
 
-Write the basic implementation for re-use: separate authorization logic and search logic
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+##### Write the basic implementation for re-use: separate authorization logic and search logic
 
 The logic of such repository may be separated into two logic:
 
@@ -803,8 +711,6 @@ This logic should be separated into your implementation.
 
 Considering this simple interface:
 
-.. code-block:: php
-
    interface MyEntityACLAwareRepositoryInterface {
 
        public function countByAuthorized(array $criterias): int;
@@ -815,15 +721,11 @@ Considering this simple interface:
 
 The base implementation should separate the logic to allow an easy reuse. Here, the method ``buildQuery`` build a basic query without authorization logic, which can be re-used. The authorization logic is dedicated to a private method. For ease of user, the logic of adding ordering criterias and pagination parameters (``$start`` and ``$limit``) are also delegated to a public method.
 
-
-.. code-block:: php
-
    namespace Chill\MyBundle\Repository;
 
    use Doctrine\ORM\EntityManagerInterface;
    use Doctrine\ORM\QueryBuilder;
 
-
    final class MyEntityACLAwareRepository implements MyEntityACLAwareRepositoryInterface {
 
        private EntityManagerInterface $em;
@@ -875,15 +777,12 @@ The base implementation should separate the logic to allow an easy reuse. Here,
 
 Once this logic is executed, it becomes easy to make a new implementation of the repository:
 
-.. code-block:: php
-
    namespace Chill\MyOtherBundle\Repository;
 
    use Doctrine\ORM\EntityManagerInterface;
    use Doctrine\ORM\QueryBuilder;
    use Chill\MyBundle\Repository\MyEntityACLAwareRepository
 
-
    final class AnotherEntityACLAwareRepository implements MyEntityACLAwareRepositoryInterface {
 
        private EntityManagerInterface $em;
@@ -921,14 +820,8 @@ Once this logic is executed, it becomes easy to make a new implementation of the
 
 Then, register this service and decorates the old one:
 
-.. code-block:: yaml
-
    services:
        Chill\MyOtherBundle\Repository\AnotherEntityACLAwareRepository:
            autowire: true
            autoconfigure: true
-           decorates: Chill\MyBundle\Repository\MyEntityACLAwareRepositoryInterface:
-
-
-
-
+           decorates: Chill\MyBundle\Repository\MyEntityACLAwareRepositoryInterface:

docs/source/development/api.md

@@ -1,23 +1,10 @@
-.. Copyright (C)  2014 Champs Libres Cooperative SCRLFS
-   Permission is granted to copy, distribute and/or modify this document
-   under the terms of the GNU Free Documentation License, Version 1.3
-   or any later version published by the Free Software Foundation;
-   with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
-   A copy of the license is included in the section entitled "GNU
-   Free Documentation License".
-
-.. _api:
-
-API
-###
+# API
 
 Chill provides a basic framework to build REST api.
 
-Basic configuration
-*******************
+###### Basic configuration
 
-Configure a route
-=================
+## Configure a route
 
 Follow those steps to build a REST api:
 
@@ -27,36 +14,29 @@ Follow those steps to build a REST api:
 You can also:
 
 * hook into the controller to customize some steps;
-* add more route and steps
-
-.. note::
+* add more routes and steps
 
     Useful links:
 
-    * `How to use annotation to configure serialization <https://symfony.com/doc/current/serializer.html>`_
-    * `How to create your custom normalizer <https://symfony.com/doc/current/serializer/custom_normalizer.html>`_
+    * [How to use annotation to configure serialization ](https://symfony.com/doc/current/serializer.html)
+    * [How to create your custom normalizer ](https://symfony.com/doc/current/serializer/custom_normalizer.html)
 
-Auto-loading the routes
-=======================
+## Autoloading the routes
 
 Ensure that those lines are present in your file `app/config/routing.yml`:
 
-
-.. code-block:: yaml
-
+```yaml
    chill_cruds:
        resource: 'chill_main_crud_route_loader:load'
        type: service
+```
 
+## Create your model
 
-Create your model
-=================
+Create your model in the usual way:
 
-Create your model on the usual way:
-
-.. code-block:: php
-
-   namespace Chill\PersonBundle\Entity\AccompanyingPeriod;
+```php
+namespace Chill\PersonBundle\Entity\AccompanyingPeriod;
 
    use Chill\PersonBundle\Entity\AccompanyingPeriod\OriginRepository;
    use Doctrine\ORM\Mapping as ORM;
@@ -87,16 +67,14 @@ Create your model on the usual way:
        // .. getters and setters
 
    }
+```
 
+## Configure api
 
-Configure api
-=============
+Configure the api using YAML (see the full configuration: [api_full_configuration](api_full_configuration.md)):
 
-Configure the api using Yaml (see the full configuration: :ref:`api_full_configuration`):
-
-.. code-block:: yaml
-
-   # config/packages/chill_main.yaml
+```yaml
+# config/packages/chill_main.yaml
    chill_main:
        apis:
            accompanying_period_origin:
@@ -113,15 +91,13 @@ Configure the api using Yaml (see the full configuration: :ref:`api_full_configu
                        methods:
                            GET: true
                            HEAD: true
+```
+   If you are working on a shared bundle (aka "The chill bundles"), you should define your configuration inside the class `ChillXXXXBundleExtension`, using the "prependConfig" feature:
 
-.. note::
-
-   If you are working on a shared bundle (aka "The chill bundles"), you should define your configuration inside the class :code:`ChillXXXXBundleExtension`, using the "prependConfig" feature:
-
-   .. code-block:: php
-
+```php
       namespace Chill\PersonBundle\DependencyInjection;
 
+
       use Symfony\Component\DependencyInjection\ContainerBuilder;
       use Symfony\Component\DependencyInjection\Extension\PrependExtensionInterface;
       use Symfony\Component\HttpFoundation\Request;
@@ -155,13 +131,13 @@ Configure the api using Yaml (see the full configuration: :ref:`api_full_configu
                           'base_role' => 'ROLE_USER',
                           'actions' => [
                               '_index' => [
-                                  'methods' => [ 
+                                  'methods' => [
                                       Request::METHOD_GET => true,
                                       Request::METHOD_HEAD => true
                                   ],
                               ],
                               '_entity' => [
-                                  'methods' => [ 
+                                  'methods' => [
                                       Request::METHOD_GET => true,
                                       Request::METHOD_HEAD => true
                                   ]
@@ -172,37 +148,35 @@ Configure the api using Yaml (see the full configuration: :ref:`api_full_configu
               ]);
           }
       }
+```
 
-The :code:`_index` and :code:`_entity` action
-*********************************************
+###### The `_index` and `_entity` action
 
-The :code:`_index` and :code:`_entity` action are default actions:
+The `_index` and `_entity` action are default actions:
 
 * they will call a specific method in the default controller;
 * they will generate defined routes:
 
 Index:
-   Name: :code:`chill_api_single_accompanying_period_origin__index`
+   Name: `chill_api_single_accompanying_period_origin__index`
 
-   Path: :code:`/api/1.0/person/accompanying-period/origin.{_format}`
+   Path: `/api/1.0/person/accompanying-period/origin.{_format}`
 
 Entity:
-   Name: :code:`chill_api_single_accompanying_period_origin__entity`
+   Name: `chill_api_single_accompanying_period_origin__entity`
 
-   Path: :code:`/api/1.0/person/accompanying-period/origin/{id}.{_format}`
+   Path: `/api/1.0/person/accompanying-period/origin/{id}.{_format}`
 
-Role
-****
+###### Role
 
-By default, the key `base_role` is used to check ACL. Take care of creating the :code:`Voter` required to take that into account.
+By default, the key `base_role` is used to check ACL. Take care of creating the `Voter` required to take that into account.
 
-For index action, the role will be called with :code:`NULL` as :code:`$subject`. The retrieved entity will be the subject for single queries.
+For index action, the role will be called with `NULL` as `$subject`. The retrieved entity will be the subject for single queries.
 
 You can also define a role for each method. In this case, this role is used for the given method, and, if any, the base role is taken into account.
 
-.. code-block:: yaml
-
-   # config/packages/chill_main.yaml
+```yaml
+# config/packages/chill_main.yaml
    chill_main:
        apis:
            accompanying_period_origin:
@@ -217,16 +191,13 @@ You can also define a role for each method. In this case, this role is used for
                        roles:
                            GET: MY_ROLE_SEE
                            HEAD: MY ROLE_SEE
+```
 
-Customize the controller
-************************
-
-You can customize the controller by hooking into the default actions. Take care of extending :code:`Chill\MainBundle\CRUD\Controller\ApiController`.
-
-
-.. code-block:: php
+###### Customize the controller
 
+You can customize the controller by hooking into the default actions. Take care of extending `Chill\MainBundle\CRUD\Controller\ApiController`.
 
+```php
    namespace Chill\PersonBundle\Controller;
 
    use Chill\MainBundle\CRUD\Controller\ApiController;
@@ -240,14 +211,14 @@ You can customize the controller by hooking into the default actions. Take care
            $qb->where($qb->expr()->gt('e.noActiveAfter', ':now'))
                ->orWhere($qb->expr()->isNull('e.noActiveAfter'));
            $qb->setParameter('now', new \DateTime('now'));
-       }     
+       }
    }
+```
 
 And set your controller in configuration:
 
-.. code-block:: yaml
-
-   chill_main:
+```yaml
+    chill_main:
        apis:
            accompanying_period_origin:
                base_path: '/api/1.0/person/accompanying-period/origin'
@@ -265,15 +236,15 @@ And set your controller in configuration:
                        methods:
                            GET: true
                            HEAD: true
+```
 
-Create your own actions
-***********************
+###### Create your own actions
 
 You can add your own actions:
 
-.. code-block:: yaml
+```yaml
 
-   chill_main:
+chill_main:
        apis:
            -
                class: Chill\PersonBundle\Entity\AccompanyingPeriod
@@ -281,7 +252,7 @@ You can add your own actions:
                base_path: /api/1.0/person/accompanying-course
                controller: Chill\PersonBundle\Controller\AccompanyingCourseApiController
                actions:
-                   # add a custom participation:
+                   # add custom participation:
                    participation:
                        methods:
                            POST: true
@@ -296,13 +267,13 @@ You can add your own actions:
                            HEAD: null
                            PUT: null
                        single-collection: single
+```
 
-The key :code:`single-collection` with value :code:`single` will add a :code:`/{id}/ + "action name"` (in this example, :code:`/{id}/participation`) into the path, after the base path. If the value is :code:`collection`, no id will be set, but the action name will be append to the path.
+The key `single-collection` with value `single` will add a `/{id}/ + "action name"` (in this example, `/{id}/participation`) into the path, after the base path. If the value is `collection`, no id will be set, but the action name will be append to the path.
 
 Then, create the corresponding action into your controller:
 
-.. code-block:: php
-
+```php
    namespace Chill\PersonBundle\Controller;
 
    use Chill\MainBundle\CRUD\Controller\ApiController;
@@ -326,10 +297,10 @@ Then, create the corresponding action into your controller:
            $this->eventDispatcher = $eventDispatcher;
            $this->validator = $validator;
        }
-       
+
        public function participationApi($id, Request $request, $_format)
        {
-           /** @var AccompanyingPeriod $accompanyingPeriod */ 
+           /** @var AccompanyingPeriod $accompanyingPeriod */
            $accompanyingPeriod = $this->getEntity('participation', $id, $request);
            $person = $this->getSerializer()
                ->deserialize($request->getContent(), Person::class, $_format, []);
@@ -363,20 +334,18 @@ Then, create the corresponding action into your controller:
            return $this->json($participation);
        }
    }
+```
 
-Managing association
-********************
+###### Managing association
 
-ManyToOne association
-=====================
+## ManyToOne association
 
-In ManyToOne association, you can add associated entities using the :code:`PATCH` request. By default, the serializer deserialize entities only with their id and discriminator type, if any.
+In ManyToOne association, you can add associated entities using the `PATCH` request. By default, the serializer deserialize entities only with their id and discriminator type, if any.
 
 Example:
 
-.. code-block:: bash
-
-   curl -X 'PATCH' \
+```
+curl -X 'PATCH' \
      'http://localhost:8001/api/1.0/person/accompanying-course/2668.json' \
      -H 'accept: */*' \
      -H 'Content-Type: application/json' \
@@ -386,16 +355,15 @@ Example:
      "id": 2668,
      "origin": { "id": 11 }
    }'
+```
 
-ManyToMany associations
-=======================
+## ManyToMany associations
 
-In OneToMany association, you can easily create route for adding and removing entities, using :code:`POST` and :code:`DELETE` requests.
+In OneToMany association, you can easily create route for adding and removing entities, using `POST` and `DELETE` requests.
 
-Prepare your entity, creating the methods :code:`addYourEntity` and :code:`removeYourEntity`:
-
-.. code-block:: php
+Prepare your entity, creating the methods `addYourEntity` and `removeYourEntity`:
 
+```php
    namespace Chill\PersonBundle\Entity;
 
    use Chill\MainBundle\Entity\Scope;
@@ -437,12 +405,12 @@ Prepare your entity, creating the methods :code:`addYourEntity` and :code:`remov
        {
            $this->scopes->removeElement($scope);
        }
-
+```
 
 Create your route into the configuration:
 
-.. code-block:: yaml
-
+```yaml
+   # config/packages/chill_main.yaml`
    chill_main:
        apis:
            -
@@ -469,14 +437,12 @@ Create your route into the configuration:
                        controller_action: null
                        path: null
                        single-collection: single
+```
 
 This will create a new route, which will accept two methods: DELETE and POST:
 
-.. code-block:: raw
-
    +--------------+---------------------------------------------------------------------------------------+
    | Property     | Value                                                                                 |
-   +--------------+---------------------------------------------------------------------------------------+
    | Route Name   | chill_api_single_accompanying_course_scope                                            |
    | Path         | /api/1.0/person/accompanying-course/{id}/scope.{_format}                              |
    | Path Regex   | {^/api/1\.0/person/accompanying\-course/(?P<id>[^/]++)/scope\.(?P<_format>[^/]++)$}sD |
@@ -488,14 +454,10 @@ This will create a new route, which will accept two methods: DELETE and POST:
    | Class        | Symfony\Component\Routing\Route                                                       |
    | Defaults     | _controller: csapi_accompanying_course_controller:scopeApi                            |
    | Options      | compiler_class: Symfony\Component\Routing\RouteCompiler                               |
-   +--------------+---------------------------------------------------------------------------------------+
-
-
 
 Then, create the controller action. Call the method:
 
-.. code-block:: php
-
+```php
    namespace Chill\PersonBundle\Controller;
 
    use Chill\MainBundle\CRUD\Controller\ApiController;
@@ -510,14 +472,14 @@ Then, create the controller action. Call the method:
            return $this->addRemoveSomething('scope', $id, $request, $_format, 'scope', Scope::class, [ 'groups' => [ 'read' ] ]);
        }
    }
+```
 
-This will allow to add a scope by his id, and delete them.
+This will allow adding a scope by his id and deleting them.
 
 Curl requests:
 
-.. code-block:: bash
-
-   # add a scope with id 5
+```
+# add a scope with id 5
    curl -X 'POST' \
      'http://localhost:8001/api/1.0/person/accompanying-course/2868/scope.json' \
      -H 'accept: */*' \
@@ -536,14 +498,13 @@ Curl requests:
      "id": 5,
      "type": "scope"
    }'
+```
 
-Deserializing an association where multiple types are allowed
-=============================================================
+## Deserializing an association where multiple types are allowed
 
-Sometimes, multiples types are allowed as association to one entity:
-
-.. code-block:: php
+Sometimes, multiple types are allowed as association to one entity:
 
+```php
    namespace Chill\PersonBundle\Entity\AccompanyingPeriod;
 
    use Chill\PersonBundle\Entity\Person;
@@ -553,7 +514,6 @@ Sometimes, multiples types are allowed as association to one entity:
    class Resource
    {
 
-
        /**
         * @ORM\ManyToOne(targetEntity=ThirdParty::class)
         * @ORM\JoinColumn(nullable=true)
@@ -566,7 +526,6 @@ Sometimes, multiples types are allowed as association to one entity:
         */
        private $person;
 
-
        /**
         *
         * @param $resource Person|ThirdParty
@@ -575,8 +534,8 @@ Sometimes, multiples types are allowed as association to one entity:
        {
           // ...
        }
-       
-       
+
+
        /**
         * @return ThirdParty|Person
         * @Groups({"read", "write"})
@@ -586,13 +545,13 @@ Sometimes, multiples types are allowed as association to one entity:
            return $this->person ?? $this->thirdParty;
        }
    }
+```
 
 This is not well taken into account by the Symfony serializer natively.
 
 You must, then, create your own CustomNormalizer. You can help yourself using this:
 
-.. code-block:: php
-
+```php
    namespace Chill\PersonBundle\Serializer\Normalizer;
 
    use Chill\PersonBundle\Entity\Person;
@@ -606,7 +565,6 @@ You must, then, create your own CustomNormalizer. You can help yourself using th
    use Symfony\Component\Serializer\Exception;
    use Chill\MainBundle\Serializer\Normalizer\DiscriminatedObjectDenormalizer;
 
-
    class AccompanyingPeriodResourceNormalizer implements DenormalizerInterface, DenormalizerAwareInterface
    {
        use DenormalizerAwareTrait;
@@ -632,35 +590,34 @@ You must, then, create your own CustomNormalizer. You can help yourself using th
                    DiscriminatedObjectDenormalizer::TYPE,
                    $format,
                    // into the context, we add the list of allowed types:
-                   [ 
-                       DiscriminatedObjectDenormalizer::ALLOWED_TYPES => 
-                       [ 
+                   [
+                       DiscriminatedObjectDenormalizer::ALLOWED_TYPES =>
+                       [
                            Person::class, ThirdParty::class
                        ]
                    ]
                );
 
                $resource->setResource($res);
-           } 
+           }
 
            return $resource;
        }
-       
+
 
        public function supportsDenormalization($data, string $type, string $format = null)
        {
            return $type === Resource::class;
-       }  
+       }
    }
+```
 
-Serialization for collection
-****************************
+###### Serialization for collection
 
 A specific model has been defined for returning collection:
 
-.. code-block:: json
-
-   {
+```
+{
        "count": 49,
        "results": [
        ],
@@ -672,13 +629,13 @@ A specific model has been defined for returning collection:
            "items_per_page": 1
        }
    }
+```
 
 Where this is relevant, this model should be re-used in custom controller actions.
 
-In custom actions, this can be achieved quickly by assembling results into a :code:`Chill\MainBundle\Serializer\Model\Collection`. The pagination information is given by using :code:`Paginator` (see :ref:`Pagination <pagination-ref>`).
-
-.. code-block:: php
+In custom actions, this can be achieved quickly by assembling results into a `Chill\MainBundle\Serializer\Model\Collection`. The pagination information is given by using `Paginator` (see [Pagination ](pagination-ref.md)).
 
+```php
    use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
    use Chill\MainBundle\Pagination\PaginatorInterface;
 
@@ -692,15 +649,11 @@ In custom actions, this can be achieved quickly by assembling results into a :co
            return $this->json($model, Response::HTTP_OK, [], $context);
        }
    }
+```
 
+###### Full configuration example
 
-.. _api_full_configuration:
-
-Full configuration example
-**************************
-
-.. code-block:: yaml
-
+```yaml
        apis:
            -
                class: Chill\PersonBundle\Entity\AccompanyingPeriod
@@ -743,5 +696,4 @@ Full configuration example
                        path: null
                        single-collection: single
                base_role: null
-
-
+```

docs/source/development/assets.md

@@ -1,91 +1,61 @@
-
-.. Copyright (C)  2014 Champs Libres Cooperative SCRLFS
-   Permission is granted to copy, distribute and/or modify this document
+Permission is granted to copy, distribute and/or modify this document
    under the terms of the GNU Free Documentation License, Version 1.3
    or any later version published by the Free Software Foundation;
    with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
    A copy of the license is included in the section entitled "GNU
    Free Documentation License".
 
-.. _forms:
-
-Assets
-#######
+# Assets
 
 The Chill assets (js, css, images, …) can be managed by `Webpack Encore`_, which is a thin wrapper for `Webpack`_ in Symfony applications.
 
-Installation
-************
+###### Installation
 
 Webpack Encore needs to be run in a Node.js environment, using the Yarn package manager. This Node.js environment can be set up using a node docker image. The bash script `docker-node.sh` set up a Node.js environment with an adequate configuration. Launch this container by typing:
 
-
-.. code-block:: bash
-
     $ bash docker-node.sh
 
 In this NodeJS environment, install all the assets required by Chill with:
 
-.. code-block:: bash
-
     node@b91cab4f7cfc:/app$ yarn install
 
 This command will install all the packages that are listed in `package.json`.
 
 Any further required dependencies can be installed using the Yarn package. For instance, jQuery is installed by:
 
-.. code-block:: bash
-
    node@b91cab4f7cfc:/app$ yarn add jquery --dev
 
+###### Usage
 
-Usage
-*****
-
-Organize your assets
---------------------
+### Organize your assets
 
 Chill assets usually lives under the `/Resources/public` folder of each Chill bundle. The Webpack configuration set up in `webpack.config.js` automatically loads the required assets from the Chill bundles that are used.
 
 For adding your own assets to Webpack, you must add an entry in the `webpack.config.js` file. For instance, the following entry will output a file `main.js` collecting the js code (and possibly css, image, etc.) from `./assets/main.js`.
 
-.. code-block:: js
-
    	.addEntry('main', './assets/main.js')
 
 To gather the css files, simply connect them to your js file, using `require`. The css file is seen as a dependency of your js file. :
 
-.. code-block:: js
-
     // assets/js/main.js
     require('../css/app.css');
 
 For finer configuration of webpack encore, we refer to the above-linked documentation.
 
-
-Compile the assets
-------------------
+### Compile the assets
 
 To compile the assets, run this line in the NodeJS container:
 
-.. code-block:: bash
-
    	node@b91cab4f7cfc:/app$ yarn run encore dev
 
 While developing, you can tell Webpack Encore to continuously watch the files you are modifying:
 
-.. code-block:: bash
-
     node@b91cab4f7cfc:/app$ yarn run encore dev --watch
 
-
-Use the assets in the templates
---------------------------------
+### Use the assets in the templates
 
 Any entry defined in the webpack.config.js file can be linked to your application using the symfony `asset` helper:
 
-.. code-block:: html
-
     <head>
         ...
         <link rel="stylesheet" href="{{ asset('build/app.css') }}">
@@ -93,12 +63,4 @@ Any entry defined in the webpack.config.js file can be linked to your applicatio
     <body>
         ...
         <script src="{{ asset('build/app.js') }}"></script>
-    </body>
-
-
-
-
-
-
-.. _Webpack Encore: https://www.npmjs.com/package/@symfony/webpack-encore
-.. _Webpack: https://webpack.js.org/
+    </body>

docs/source/development/code-quality.md

@@ -0,0 +1,23 @@
+# Code style, code quality and other tools
+
+## PHP-cs-fixer
+
+For development, you will also have to install:
+
+- [php-cs-fixer ](https://cs.symfony.com/)
+
+We also encourage you to use tools like [phpstan ](https://phpstan.org) and [rector ](https://getrector.com).
+
+For running php-cs-fixer:
+
+   symfony composer php-cs-fixer
+
+## Execute tests
+
+   symfony composer exec phpunit -- /path/to_your_test.php
+
+Note that IDE like PhpStorm should be able to run tests, even KernelTestcase or WebTestCase, [from within their interfaces ](https://www.jetbrains.com/help/phpstorm/using-phpunit-framework.html#run_phpunit_tests).
+
+## Execute rector
+
+   symfony composer exec rector -- process

docs/source/development/code-quality.rst

@@ -1,34 +0,0 @@
-Code style, code quality and other tools
-########################################
-
-PHP-cs-fixer
-============
-
-For development, you will also have to install:
-
-- `php-cs-fixer <https://cs.symfony.com/>`_
-
-We also encourage you to use tools like `phpstan <https://phpstan.org>`_ and `rector <https://getrector.com>`_.
-
-For running php-cs-fixer:
-
-.. code-block:: bash
-
-   symfony composer php-cs-fixer
-
-Execute tests
-=============
-
-.. code-block:: bash
-
-   symfony composer exec phpunit -- /path/to_your_test.php
-
-Note that IDE like PhpStorm should be able to run tests, even KernelTestcase or WebTestCase, `from within their interfaces <https://www.jetbrains.com/help/phpstorm/using-phpunit-framework.html#run_phpunit_tests>`_.
-
-Execute rector
-==============
-
-.. code-block:: bash
-
-   symfony composer exec rector -- process
-

docs/source/development/create-a-new-bundle.md

@@ -1,15 +1,11 @@
-.. Copyright (C)  2014 Champs Libres Cooperative SCRLFS
-   Permission is granted to copy, distribute and/or modify this document
+Permission is granted to copy, distribute and/or modify this document
    under the terms of the GNU Free Documentation License, Version 1.3
    or any later version published by the Free Software Foundation;
    with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
    A copy of the license is included in the section entitled "GNU
    Free Documentation License".
 
-.. _create-new-bundle:
-
-Create a new bundle
-*******************
+###### Create a new bundle
 
 Create your own bundle is not a trivial task.
 
@@ -19,16 +15,9 @@ The easiest way to achieve this is seems to be :
 2. Create a new bundle in this project, in the src directory
 3. Initialize a git repository **at the root bundle**, and create your initial commit.
 4. Register the bundle with composer/packagist. If you do not plan to distribute your bundle with packagist, you may use a custom repository for achieve this [#f1]_
-5. Move to a development installation, made as described in the :ref:`installation-for-development` section, and add your new repository to the composer.json file
-6. Work as :ref:`usual <editing-code-and-commiting>`
-
-.. warning::
+5. Move to a development installation, made as described in the [installation-for-development` section, and add your new repository to the composer.json file
+6. Work as :ref:`usual ](editing-code-and-commiting.md)
 
     This part of the doc is not yet tested
 
-TODO
-
-
-.. rubric:: Footnotes
-
-.. [#f1] Be aware that we use the Affero GPL Licence, which ensure that all users must have access to derivative works done with this software.
+TODO

docs/source/development/cronjob.md

@@ -1,37 +1,26 @@
-
-.. Copyright (C)  2014-2023 Champs Libres Cooperative SCRLFS
-    Permission is granted to copy, distribute and/or modify this document
+Permission is granted to copy, distribute and/or modify this document
     under the terms of the GNU Free Documentation License, Version 1.3
     or any later version published by the Free Software Foundation;
     with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
     A copy of the license is included in the section entitled "GNU
     Free Documentation License".
 
-.. _cronjob:
-
-Cron jobs
-*********
+###### Cron jobs
 
 Some tasks must be executed regularly: refresh some materialized views, remove old data, ...
 
 For this purpose, one can programmatically implements a "cron job", which will be scheduled by a specific command.
 
-The command :code:`chill:cron-job:execute`
-==========================================
+## The command `chill:cron-job:execute`
 
-The command :code:`chill:cron-job:execute` will schedule a task, one by one. In a classical implementation, it should
+The command `chill:cron-job:execute` will schedule a task, one by one. In a classical implementation, it should
 be executed every 15 minutes (more or less), to ensure that every task can be executed.
 
-.. warning::
-
    This command should not be executed in parallel. The installer should ensure that two job are executed concurrently.
 
-How to implements a cron job ?
-==============================
+## How to implements a cron job ?
 
-Implements a :code:`Chill\MainBundle\Cron\CronJobInterface`. Here is an example:
-
-.. code-block:: php
+Implements a `Chill\MainBundle\Cron\CronJobInterface`. Here is an example:
 
     namespace Chill\MainBundle\Service\Something;
 
@@ -83,19 +72,15 @@ Implements a :code:`Chill\MainBundle\Cron\CronJobInterface`. Here is an example:
        }
     }
 
-How are cron job scheduled ?
-============================
+## How are cron job scheduled ?
 
-If the command :code:`chill:cron-job:execute` is run with one or more :code:`job` argument, those jobs are run, **without checking that the job can run** (the method :code:`canRun` is not executed).
+If the command `chill:cron-job:execute` is run with one or more `job` argument, those jobs are run, **without checking that the job can run** (the method `canRun` is not executed).
 
-If any :code:`job` argument is given, the :code:`CronManager` schedule job with those steps:
+If any `job` argument is given, the `CronManager` schedule job with those steps:
 
 * the tasks are ordered, with:
    * a priority is given for tasks that weren't never executed;
    * then, the tasks are ordered, the last executed are the first in the list
-* then, for each tasks, and in the given order, the first task where :code:`canRun` return :code:`TRUE` will be executed.
-
-The command :code:`chill:cron-job:execute` execute **only one** task.
-
-
+* then, for each tasks, and in the given order, the first task where `canRun` return `TRUE` will be executed.
 
+The command `chill:cron-job:execute` execute **only one** task.

docs/source/development/crud.md

@@ -1,15 +1,11 @@
-.. Copyright (C)  2014 Champs Libres Cooperative SCRLFS
-   Permission is granted to copy, distribute and/or modify this document
+Permission is granted to copy, distribute and/or modify this document
    under the terms of the GNU Free Documentation License, Version 1.3
    or any later version published by the Free Software Foundation;
    with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
    A copy of the license is included in the section entitled "GNU
    Free Documentation License".
 
-.. _crud:
-
-CRUD
-####
+# CRUD
 
 Chill provide an API to create a basic CRUD.
 
@@ -20,30 +16,21 @@ One can follow those steps to create a CRUD for one entity:
 3. customize the templates if required ;
 4. customize some steps of the controller if required ;
 
+An example with the [`ClosingMotive`` (PersonBundle) in the admin part of Chill:
 
-An example with the ``ClosingMotive`` (PersonBundle) in the admin part of Chill: 
-
-Auto-loading the routes
-***********************
+###### Auto-loading the routes
 
 Ensure that those lines are present in your file `app/config/routing.yml`:
 
-
-.. code-block:: yaml
-
    chill_cruds:
        resource: 'chill_main_crud_route_loader:load'
        type: service
 
-
-
-Create your model
-*****************
+###### Create your model
 
 Create your model on the usual way (in this example, ORM informations are stored in yaml file):
 
-.. code-block:: php
-
+```php
    namespace Chill\PersonBundle\Entity\AccompanyingPeriod;
 
    use Doctrine\Common\Collections\Collection;
@@ -62,41 +49,40 @@ Create your model on the usual way (in this example, ORM informations are stored
         * @var array
         */
        private $name;
-       
+
        /**
         *
         * @var boolean
         */
        private $active = true;
-       
+
        /**
         *
         * @var self
         */
        private $parent = null;
-       
+
        /**
         * child Accompanying periods
         *
         * @var Collection
         */
        private $children;
-       
+
        /**
         *
         * @var float
         */
        private $ordering = 0.0;
 
-
        // getters and setters come here
 
    }
+```
 
 The form:
 
-.. code-block:: php
-
+```php
    namespace Chill\PersonBundle\Form;
 
    use Symfony\Component\Form\AbstractType;
@@ -108,8 +94,7 @@ The form:
    use Symfony\Component\Form\Extension\Core\Type\NumberType;
 
    /**
-    *
-    *
+###### *
     */
    class ClosingMotiveType extends AbstractType
    {
@@ -145,22 +130,21 @@ The form:
                ;
        }
    }
+```
 
-Configure the crud
-******************
+###### Configure the crud
 
 The crud is configured using the key ``crud`` under ``chill_main``
 
-.. code-block:: yaml
-
+```yaml
    chill_main:
      cruds:
-       - 
+       -
          # the class which is concerned by the CRUD
          class: '\Chill\PersonBundle\Entity\AccompanyingPeriod\ClosingMotive::class'
          # give a name for the crud. This will be used internally
          name: closing_motive
-         # add a base path for the 
+         # add a base path for the
          base_path: /admin/closing-motive
          # this is the form class
          form_class: 'Chill\PersonBundle\Form\ClosingMotiveType::class'
@@ -170,8 +154,8 @@ The crud is configured using the key ``crud`` under ``chill_main``
          # this is a list of action you can configure
          # by default, the actions `index`, `view`, `new` and `edit` are automatically create
          # you can add more actions or configure some details about them
-         actions: 
-            index: 
+         actions:
+            index:
               # the default template for index is very poor,
               # you will need to override it
               template: '@ChillPerson/ClosingMotive/index.html.twig'
@@ -180,16 +164,16 @@ The crud is configured using the key ``crud`` under ``chill_main``
             new:
               role: ROLE_ADMIN
               # by default, the template will only show the form
-              # you can override it 
+              # you can override it
               template: '@ChillPerson/ClosingMotive/new.html.twig'
             edit:
               role: ROLE_ADMIN
               template: '@ChillPerson/ClosingMotive/edit.html.twig'
+```
 
-To leave the bundle auto-configure the ``chill_main`` bundle, you can `prepend the configuration of the ChillMain Bundle <https://symfony.com/doc/current/bundles/prepend_extension.html>`_:
-
-.. code-block:: php
+To leave the bundle autoconfigure the ``chill_main`` bundle, you can `prepend the configuration of the ChillMain Bundle ](https://symfony.com/doc/current/bundles/prepend_extension.html):
 
+```php
    namespace Chill\PersonBundle\DependencyInjection;
 
    use Symfony\Component\DependencyInjection\ContainerBuilder;
@@ -204,13 +188,13 @@ To leave the bundle auto-configure the ``chill_main`` bundle, you can `prepend t
        {
            // skipped here
        }
-       
-       
-       public function prepend(ContainerBuilder $container) 
+
+
+       public function prepend(ContainerBuilder $container)
        {
            $this->prependCruds($container);
        }
-       
+
        protected function prependCruds(ContainerBuilder $container)
        {
            $container->prependExtensionConfig('chill_main', [
@@ -240,20 +224,17 @@ To leave the bundle auto-configure the ``chill_main`` bundle, you can `prepend t
            ]);
        }
    }
+```
 
+###### Customize templates
 
-
-Customize templates
-*******************
-
-The current template are quite basic. You can override and extends them.
+The current template is quite basic. You can override and extends them.
 
 For a better inclusion, you can embed them instead of extending them.
 
 For index. Note that we extend here the `admin` layout, not the default one:
 
-.. code-block:: html+jinja
-
+```php
    {% extends '@ChillMain/Admin/layout.html.twig' %}
 
    {% block admin_content %}
@@ -288,11 +269,11 @@ For index. Note that we extend here the `admin` layout, not the default one:
            {% endblock %}
        {% endembed %}
    {% endblock %}
+```
 
 For edit template:
 
-.. code-block:: html+jinja
-
+```php
    {% extends '@ChillMain/Admin/layout.html.twig' %}
 
    {% block title %}
@@ -309,8 +290,6 @@ For edit template:
 
 For new template:
 
-.. code-block:: html+jinja
-
    {% extends '@ChillMain/Admin/layout.html.twig' %}
 
    {% block title %}
@@ -322,17 +301,16 @@ For new template:
        {% block content_form_actions_save_and_show %}{% endblock %}
    {% endembed %}
    {% endblock %}
+```
 
-Customize some steps in the controller
-**************************************
+###### Customize some steps in the controller
 
 Some steps may be customized by overriding the default controller and some methods. Here, we will override the way the entity is created, and the ordering of the "index" page:
 
 * we will associate a parent ClosingMotive to the element if a parameter `parent_id` is found ;
 * we will order the ClosingMotive by the ``ordering`` property
 
-.. code-block:: php
-
+```php
    namespace Chill\PersonBundle\Controller;
 
    use Chill\MainBundle\CRUD\Controller\CRUDController;
@@ -376,14 +354,13 @@ Some steps may be customized by overriding the default controller and some metho
            return $query->orderBy('e.ordering', 'ASC');
        }
    }
+```
 
-How-to and questions
-********************
+###### How-to and questions
 
-Which role is required for each action ?
-========================================
+## Which role is required for each action ?
 
-By default, each action will use: 
+By default, each action will use:
 
 1. the role defined under the action key ;
 2. the base role as upper, with the action name appended:
@@ -396,22 +373,21 @@ By default, each action will use:
 The entity will be passed to the role:
 
 * for the ``view`` and ``edit`` action: the entity fetched from database
-* for the ``new`` action: the entity which is created (you can override default values using 
-* for index action (or if you re-use the ``indexAction`` method: ``null``  
-  
-How to add some route and actions ?
-===================================
+* for the ``new`` action: the entity which is created (you can override default values using
+* for index action (or if you re-use the ``indexAction`` method: ``null``
+
+## How to add some route and actions ?
 
 Add them under the action key:
 
-.. code-block:: yaml
-
+```yaml
    chill_main:
      cruds:
-       - 
+       -
          # snipped
          actions:
            myaction: ~
+```
 
 The method `myactionAction` will be called by the parameter.
 
@@ -419,13 +395,12 @@ Inside this action, you can eventually call another internal method:
 
 * ``indexAction`` for a list of items ;
 * ``viewAction`` for a view
-* ``editFormAction`` for an edition 
+* ``editFormAction`` for an edition
 * ``createFormAction`` for a creation
 
 Example:
 
-.. code-block:: php
-
+```php
    namespace CSConnectes\SPBundle\Controller;
 
    use Chill\PersonBundle\CRUD\Controller\OneToOneEntityPersonCRUDController;
@@ -456,34 +431,29 @@ Example:
        }
 
    }
+```
 
-How to create a CRUD for entities associated to persons
-=======================================================
+## How to create a CRUD for entities associated to persons
 
 The bundle person provide some controller and template you can override, instead of the ones present in the mainbundle:
 
-* :code:`Chill\PersonBundle\CRUD\Controller\EntityPersonCRUDController` for entities linked with a one-to-may association to :code:`Person` class ;
-* :code:`Chill\PersonBundle\CRUD\Controller\OneToOneEntityPersonCRUDController` for entities linked with a one-to-one association to :code:`Person` class.
+* `Chill\PersonBundle\CRUD\Controller\EntityPersonCRUDController` for entities linked with a one-to-may association to `Person` class ;
+* `Chill\PersonBundle\CRUD\Controller\OneToOneEntityPersonCRUDController` for entities linked with a one-to-one association to `Person` class.
 
 There are also template defined under ``@ChillPerson/CRUD/`` namespace.
 
-Those controller assume that:
+Those controllers assume that:
 
-* the entity provide the method :code:`getPerson` and :code:`setPerson` ;
+* the entity provide the method `getPerson` and `setPerson` ;
 * the `index`'s id path will be the id of the person, and the ids in `view` and `edit` path will be the id of the entity ;
 
-This bundle also use by default the templates inside ``@ChillPerson/CRUD/``.
+This bundle also uses by default the templates inside ``@ChillPerson/CRUD/``.
 
+###### Reference
 
-Reference
-*********
-
-Configuration reference
-=======================
-
-
-.. code-block:: txt
+## Configuration reference
 
+```yaml
    chill_main:
        cruds:
 
@@ -514,9 +484,8 @@ Configuration reference
 
                        # the template to render the view
                        template:             null
+```
 
-Twig default block
-==================
+## Twig default block
 
 This part should be documented.
-

docs/source/development/database-principles.md

@@ -0,0 +1,70 @@
+# Database Principles
+
+This page provides a global understanding of the Chill database and explains some implementation details that help accelerate processing from the database or exploit it more easily.
+
+!!! warning "Database Schema Stability"
+    The stability of the database schema is not guaranteed.
+
+    However, it evolves relatively little. It is rare for tables or columns to be deleted or renamed, but it is not guaranteed that this cannot happen.
+
+## Overview
+
+A commented list of all tables is available in CSV format at `./database/table_list.csv`.
+
+### Schema and naming conventions
+
+At the beginning of Chill's history, PostgreSQL schemas were not used. Data was stored in the `public` schema.
+
+Later, new bundles appeared, and tables were classified into dedicated schemas.
+
+Currently:
+
+- for older bundles, those that already have tables in the public schema, new tables are added to this schema. They are prefixed with `chill_<bundle_name>_`;
+- for more recent bundles, tables are created in the dedicated schema
+
+### Historical data
+
+Some data is historized:
+
+- the referents of an accompanying period;
+- the statuses of an accompanying period;
+- the link between territories and users;
+- etc.
+
+In these cases, Chill generally creates two columns, which are usually named `startDate` and `endDate`. When the `endDate` column is `NULL`, it means that the period is not "closed". The `startDate` column is not nullable.
+
+In some cases, the current data (referent of an accompanying period, for example) is also repeated at the table level itself. For example, the accompanying periods table `chill_person_accompanying_period` has a `step` column (the status of the period) and `user_id` (referent id) in addition to the history. Although redundant, this simplifies processing.
+
+## Special relationships
+
+### Users, households, addresses
+
+Users have an address through households: in the interface, the address is recorded in the household file, and it is "given" to users who are members of the household, **and** who share the address of this household. Indeed, it is possible that users "belong" to a household without being domiciled there: this is the case, for example, for children in shared custody.
+
+The history of users' membership in the household is preserved, as well as the history of addresses for the same household.
+
+The tables involved are as follows:
+
+- the `chill_person_person` table lists the users;
+- the `chill_person_household_members` table lists household memberships: this is the junction between users and households:
+  - the `startDate` and `endDate` columns indicate the start and end date of membership;
+  - the `shareHousehold` column indicates whether the user shares the household address (if yes, its value is `TRUE`)
+- the `chill_person_household` table lists households
+- the `chill_person_household_to_addresses` table associates households with addresses;
+- the `chill_main_address` table contains addresses, indicating the validity start date (`validFrom`) and the validity end date (`validTo`).
+
+To simplify the resolution of addresses and users, two views have been implemented:
+
+- the `view_chill_person_household_address` view takes up, for each user, the history of household memberships broken down by the address history of a household.
+  In other words, a line is created each time a user changes household, or a household changes address. It is therefore possible to find the complete address history for a given user via this table.
+- the `view_chill_person_current_address` view takes up the current address of users.
+
+### Addresses and geographical units
+
+Chill provides statistics on the location of addresses relative to geographical zones (`chill_main_geographical_unit`).
+
+Since the geographical resolution of addresses is costly in CPU and processing time, a materialized view has been created: `view_chill_main_address_geographical_unit`. It is refreshed daily in the production database.
+
+## Table list and comments
+
+A commented list of all tables is available in CSV format at `./database/table_list.csv`.

docs/source/development/database-principles.rst

@@ -1,84 +0,0 @@
-
-.. database-principles:
-
-Principes de la base de données
-###############################
-
-Cette page donne une compréhension globale de la base de donnée de Chill, et explique quelques détails d'implémentations qui permettent d'accélérer les traitements à partir de la base de donnée, ou de l'exploiter plus aisément.
-
-Cette page est rédigée en français.
-
-.. note::
-
-    La stabilité du schéma de la base de donnée n'est pas garantie.
-
-    Toutefois, ce dernier évolue relativement peu. Il est rare que des tables ou des colonnes soient supprimées ou renommées. Mais il n'est pas garanti que cela puisse arriver.
-
-Généralités
-===========
-
-Une liste commentée de toutes les tables :download:`est disponible au format CSV <./database/table_list.csv`.
-
-Schéma et conventions de nommage
---------------------------------
-
-Au début de l'histoire de Chill, les schémas postgresql n'étaient pas exploités. Les données étaient stockées dans le schéma :code:`public`.
-
-Par la suite, des nouveaux bundles sont apparus, et les tables ont été classées dans des schémas dédiés.
-
-A l'heure actuelle:
-
-- pour les anciens bundle, ceux qui ont déjà des tables dans le schéma public, les nouvelles tables sont ajoutées à ce schéma. Elles sont préfixées par :code:`chill_<nom du bundle>_`;
-- pour les bundles plus récents, les tables sont créées dans le schéma dédié
-
-Données avec de l'historicité
------------------------------
-
-Certaines données sont historisées:
-
-- les référents d'un parcours;
-- les statuts d'un parcours;
-- la liaison entre les territoires et les usagers;
-- etc.
-
-Dans ces cas-là, Chill crée généralement deux colonnes, qui sont habituellement nommées :code:`startDate` et :code:`endDate`. Lorsque la colonne :code:`endDate` est à :code:`NULL`, cela signifie que la période n'est pas "fermée". La colonne :code:`startDate` n'est pas nullable.
-
-Dans certains cas, la donnée actuelle (référent d'un parcours, par exemple) est également répétée au niveau de la table en elle-même. Par exemple, la table des parcours :code:`chill_person_accompanying_period` comporte une colonne :code:`step` (le statut du parcours) et :code:`user_id` (id du référent) en plus de l'historique. Bien que redondant, cela simplifie les traitements.
-
-Relations particulières
-=======================
-
-Usagers, ménages, adresses
---------------------------
-
-Les usagers ont une adresse au travers des ménages: dans l'interface, l'adresse est inscrite dans le dossier du ménage, et elle est "donnée" aux usagers membres du ménage, **et** qui partagent l'adresse de ce ménage. En effet, il est possible que des usagers "appartiennent" à un ménage sans y être domicilié: c'est le cas, par exemple, des enfants en garde alternée.
-
-L'historique de l'appartenance des usagers au ménage est conservée, de même que l'historique des adresses pour un même ménage.
-
-Les tables en jeu sont les suivantes:
-
-- la table :code:`chill_person_person` liste les usagers;
-- la table :code:`chill_person_household_members` liste les appartenances au ménage: il s'agit de la jointure entre les usagers et les ménages:
-  - les colonnes :code:`startDate` et :code:`endDate` indiquent la date de début et la date de fin de l'appartenance;
-  - la colonne :code:`shareHousehold` indique si l'utilisateur partage l'adresse du ménage (si oui, sa valeur est :code:`TRUE`)
-- la table :code:`chill_person_household` liste les ménages
-- la table :code:`chill_person_household_to_addresses` associe les ménages aux adresses;
-- la table :code:`chill_main_address` contient les adresses, en indiquant la date de début de validité (:code:`validFrom`) et la fin de validité (:code:`validTo`).
-
-Pour simplifier la résolution des adresses et des usagers, deux vues ont été mises en œuvre:
-
-- la vue :code:`view_chill_person_household_address` reprend, pour chaque usager, l'historique des appartenances au ménage découpée par l'historique des adresses d'un ménage.
-  Autrement dit, une ligne est créée à chaque fois qu'un usager change de ménage, ou qu'un ménage change d'adresse. Il est donc possible de retrouver l'historique complet des adresses pour un usager donné via cette table.
-- la vue :code:`view_chill_person_current_address` reprend l'adresse actuelle des usagers.
-
-Adresses et unités géographiques
---------------------------------
-
-Chill propose des statistiques sur la localisation des adresses par rapport à des zones géographiques (:code:`chill_main_geographical_unit`).
-
-Comme la résolution géographique des adresses est coûteuse en CPU et en temps de traitement, une vue matérialisée a été créée: :code:`view_chill_main_address_geographical_unit`. Elle est rafraichie quotidiennement dans la base de donnée de production.
-
-Liste des tables et commentaires
-================================
-
-Une liste commentée de toutes les tables :download:`est disponible au format CSV <./database/table_list.csv`.

docs/source/development/embeddable-comments.md

@@ -1,30 +1,17 @@
-
-.. Copyright (C)  2016 Champs Libres Cooperative SCRLFS
-   Permission is granted to copy, distribute and/or modify this document
-   under the terms of the GNU Free Documentation License, Version 1.3
-   or any later version published by the Free Software Foundation;
-   with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
-   A copy of the license is included in the section entitled "GNU
-   Free Documentation License".
-
-
-Embeddable comments
-###################
+# Embeddable comments
 
 Those embeddable comments is a comment with some metadata:
 
 * the one who updated the comment (the comment itself, and not the whole entity);
 * the date and time for the last update (again, the comment itself, and not the whole entity).
 
-We make usage of `embeddables <https://www.doctrine-project.org/projects/doctrine-orm/en/2.8/tutorials/embeddables.html>`_.
+We make usage of [embeddable ](https://www.doctrine-project.org/projects/doctrine-orm/en/2.8/tutorials/embeddables.html).
 
-Embed the comment
-=================
+## Embed the comment
 
 The comment may be embedded into the entity:
 
-.. code-block:: php
-
+```php
    namespace Chill\ActivityBundle\Entity;
 
    use Chill\MainBundle\Entity\Embeddable\CommentEmbeddable;
@@ -51,7 +38,6 @@ The comment may be embedded into the entity:
         */
        private $comment;
 
-
        /**
         * @return \Chill\MainBundle\Entity\Embeddalbe\CommentEmbeddable
         */
@@ -68,27 +54,21 @@ The comment may be embedded into the entity:
            $this->comment = $comment;
        }
    }
+```
 
-Note on relation to :class:`User`
-=================================
+## Note on relation to :class:`User`
 
 The embeddable proposed by Doctrine does not support relationship to other entities. The entity Comment is able to render a user's id, but not an User object.
 
+   `$activity->getComment()->getUserId(); // return user id of the last author`
 
-.. code-block:: php
+   `$activity->getComment()->getUser(); // does not work !`
 
-   $activity->getComment()->getUserId(); // return user id of the last author
+## Usage into form
 
-   $activity->getComment()->getUser(); // does not work !
-
-
-Usage into form
-===============
-
-Use the :class:`Chill\MainBundle\Form\Type\CommentType` to load the form widget:
-
-.. code-block:: php
+Use the `Chill\MainBundle\Form\Type\CommentType` to load the form widget:
 
+```php
    namespace Chill\ActivityBundle\Form;
 
    use Chill\MainBundle\Form\Type\CommentType;
@@ -110,12 +90,8 @@ Use the :class:`Chill\MainBundle\Form\Type\CommentType` to load the form widget:
            ;
        }
    }
+```
 
-Render the comment
-==================
-
-.. code-block:: twig
-
-   {{ activity.comment|chill_entity_render_box }}
-
+## Render the comment
 
+   `{{ activity.comment|chill_entity_render_box }}`

docs/source/development/entity-info.md

@@ -1,16 +1,4 @@
-
-.. Copyright (C)  2014 Champs Libres Cooperative SCRLFS
-Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.3
-or any later version published by the Free Software Foundation;
-with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
-A copy of the license is included in the section entitled "GNU
-Free Documentation License".
-
-.. _entity-info:
-
-Stats about event on entity in php world
-########################################
+# Stats about event on entity in php world
 
 It is necessary to be able to gather information about events for some entities:
 
@@ -18,11 +6,9 @@ It is necessary to be able to gather information about events for some entities:
 - who did it;
 - ...
 
-Those "infos" are not linked with right management, like describe in :ref:`timelines`.
+Those "infos" are not linked with right management, like describe in [timelines`.
 
-
-“infos” for some stats and info about an entity
------------------------------------------------
+### “infos” for some stats and info about an entity
 
 Building an info means:
 
@@ -32,10 +18,10 @@ Building an info means:
 A framework api is built to be able to build multiple “infos” entities
 through “union” views:
 
--  use a command ``bin/console chill:db:sync-views`` to synchronize view (create view if it does not exists, or update
+-  use a command ``bin/console chill:db:sync-views`` to synchronize view (create view if it does not exist, or update
    views when new SQL parts are added in the UNION query. Internally, this command call a new ``ViewEntityInfoManager``,
    which iterate over available views to build the SQL;
--  one can create a new “view entity info” by implementing a
+-  one can create new “view entity info” by implementing a
    ``ViewEntityInfoProviderInterface``
 -  this implementation of the interface is free to create another
    interface for building each part of the UNION query. This interface
@@ -45,14 +31,13 @@ through “union” views:
 So, converting new “events” into rows for ``AccompanyingPeriodInfo`` is
 just implementing this interface!
 
-Implementation for AccompanyingPeriod (``AccompanyingPeriod/AccompanyingPeriodInfo``)
--------------------------------------------------------------------------------------
+### Implementation for AccompanyingPeriod (``AccompanyingPeriod/AccompanyingPeriodInfo``)
 
 A class is created for computing some statistical info for an
 AccompanyingPeriod: ``AccompanyingPeriod/AccompanyingPeriodInfo``. This
 contains information about “something happens”, who did it and when.
 
-Having those info in table answer some questions like:
+Having that info in the table answers some questions like:
 
 -  when is the last and the first action (AccompanyingPeriodWork,
    Activity, AccompanyingPeriodWorkEvaluation, …) on the period;
@@ -60,46 +45,43 @@ Having those info in table answer some questions like:
    user.
 
 The AccompanyingPeriod info is mapped to a SQL view, not a table. The
-sql view is built dynamically (see below), and gather infos from
+SQL view is built dynamically (see below), and gathers info from
 ActivityBundle, PersonBundle, CalendarBundle, … It is possible to create
-custom bundle and add info on this view.
-
-.. code:: php
+ a custom bundle and add info on this view.
 
+```php
    /**
     *
     * @ORM\Entity()
-    * @ORM\Table(name="view_chill_person_accompanying_period_info") <==== THIS IS A VIEW, NOT A TABLE
+    * @ORM\Table(name="view_chill_person_accompanying_period_info") ](==== THIS IS A VIEW, NOT A TABLE
     */
    class AccompanyingPeriodInfo
    {
      // ...
    }
+```
 
-Why do we need this ?
-~~~~~~~~~~~~~~~~~~~~~
+#### Why do we need this?
 
-For multiple jobs in PHP world:
+For multiple jobs in a PHP world:
 
--  moving the accompanying period to another steps when inactive,
+-  moving the accompanying period to another step when inactive,
    automatically;
 -  listing all the users which are intervening on the action on a new
    “Liste des intervenants” page;
 -  filtering on exports
 
-Later, we will launch automatic anonymise for accompanying period and
+Later we will launch automatic anonymize for an accompanying period and
 all related entities through this information.
 
-How is built the SQL views which is mapped to “info” entities ?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#### How are the SQL views built that are mapped to “info” entities?
 
 The AccompanyingPeriodInfo entity is mapped by a SQL view (not a regular
 table).
 
-The sql view is built dynamically, it is a SQL view like this, for now (April 2023):
-
-.. code:: sql
+The SQL view is built dynamically; it is a SQL view like this, for now (April 2023):
 
+```sql
    create view view_chill_person_accompanying_period_info
                (accompanyingperiod_id, relatedentity, relatedentityid, user_id, infodate, discriminator, metadata) as
    SELECT w.accompanyingperiod_id,
@@ -191,13 +173,14 @@ The sql view is built dynamically, it is a SQL view like this, for now (April 20
    FROM activity
             LEFT JOIN activity_user au ON activity.id = au.activity_id
    WHERE activity.accompanyingperiod_id IS NOT NULL;
+```
 
-As you can see, the view gather multiple SELECT queries and bind them
+As you can see, the view gathers multiple SELECT queries and binds them
 with UNION.
 
 Each SELECT query is built dynamically, through a class implementing an
 interface: ``Chill\PersonBundle\Service\EntityInfo\AccompanyingPeriodInfoUnionQueryPartInterface``, `like
-here <https://gitlab.com/Chill-Projet/chill-bundles/-/blob/master/src/Bundle/ChillPersonBundle/Service/EntityInfo/AccompanyingPeriodInfoQueryPart/AccompanyingPeriodWorkEndQueryPartForAccompanyingPeriodInfo.php>`__
+here <https://gitlab.com/Chill-Projet/chill-bundles/-/blob/master/src/Bundle/ChillPersonBundle/Service/EntityInfo/AccompanyingPeriodInfoQueryPart/AccompanyingPeriodWorkEndQueryPartForAccompanyingPeriodInfo.php.md)__
 
-To add new `SELECT` query in different `UNION` parts in the sql view, create a
+To add new `SELECT` query in different `UNION` parts in the SQL view, create a
 service and implements this interface: ``Chill\PersonBundle\Service\EntityInfo\AccompanyingPeriodInfoUnionQueryPartInterface``.

docs/source/development/es-lint.md

@@ -1,12 +1,10 @@
-ESLint
-======
+## ESLint
 
 To improve the quality of our JS and VueJS code, ESLint and eslint-plugin-vue are implemented within the chill-bundles project.
 
-Commands
---------
+### Commands
 
-To run ESLint, you can simply use the ``eslint`` command within the chill-bundles directory.
+To run ESLint, you can simply use the [`eslint`` command within the chill-bundles directory.
 This runs eslint **not** taking the baseline into account, thus showing all existing errors in the project.
 
 A script was also added to package.json allowing you to execute ``yarn run eslint``.
@@ -19,20 +17,18 @@ Interesting options that can be used in combination with eslint are:
 - ``--quiet`` to only get errors and silence the warnings
 - ``--fix`` to have ESLint fix what it can, automatically. This will not fix everything.
 
-Baseline
---------
+### Baseline
 
-To allow us the time to fix linting errors/warnings a baseline has been created using the following command
+To allow us the time to fix linting errors/warnings, a baseline has been created using the following command
 - ``npx eslint-baseline "**/*.{js,vue}"``
 
-The baseline has been commited and the gitlab CI setup to only fail upon new errors/warnings being created.
+The baseline has been committed and the gitlab CI setup to only fail upon new errors/warnings being created.
 When fixing errors/warnings manually, please update the baseline.
 
 1. Delete the current baseline file
 2. Run the above command locally, this will automatically create a new baseline that should be commited
 
-Rules
------
+### Rules
 
 We use Vue 3, so the rules can be configured as follows within the ``eslint.config.mjs`` file:
 
@@ -45,17 +41,14 @@ Configurations for using Vue.js 3.x:
 - ``.configs["flat/recommended"]`` ... Above, plus rules to enforce subjective community defaults to ensure consistency.
 
 Detailed information about which rules each set includes can be found here:
-`https://eslint.vuejs.org/rules/ <https://eslint.vuejs.org/rules/>`_
+`https://eslint.vuejs.org/rules/ ](https://eslint.vuejs.org/rules/)
 
-Manual Rule Configuration
--------------------------
+### Manual Rule Configuration
 
 We can also manually configure certain rules or override rules that are part of the ruleset specified above.
 
 For example, if we want to turn off a certain rule, we can do so as follows:
 
-.. code-block:: javascript
-
     rules: {
       'vue/multi-word-component': 'off'
     }
@@ -64,8 +57,6 @@ We could also change the severity of a certain rule from 'error' to 'warning', f
 
 Within specific ``.js`` or ``.vue`` files, we can also override a certain rule only for that specific file by adding a comment:
 
-.. code-block:: javascript
-
     /* eslint multi-word-component: "off", no-child-content: "error"
     --------
     Here's a description about why this configuration is necessary. */

docs/source/development/export-sequence.puml

@@ -1,84 +0,0 @@
-@startuml
-'https://plantuml.com/sequence-diagram
-
-autonumber
-
-User -> ExportController: configure export using form
-activate ExportController
-ExportController -> ExportForm: build form
-activate ExportForm
-
-loop for every ExportElement (Filter, Aggregator)
-    ExportForm -> ExportElement: `buildForm`
-    activate ExportElement
-    ExportElement -> ExportForm: add form to builders
-    deactivate ExportElement
-end
-
-ExportForm -> ExportController
-deactivate ExportForm
-
-ExportController -> User: show form
-deactivate ExportController
-
-note left of User: Configure the export:\ncheck filters, aggregators, …
-
-User -> ExportController: post configuration of the export
-activate ExportController
-
-ExportController -> ExportForm: `getData`
-activate ExportForm
-ExportForm -> ExportController: return data: list of entities, etc.
-deactivate ExportForm
-
-loop for every ExportElement (Filter, Aggregator)
-    ExportController -> ExportElement: serializeData (data)
-    activate ExportElement
-    ExportElement -> ExportController: return serializedData (simple array with string, int, …)
-    deactivate ExportElement
-end
-
-ExportController -> Database: `INSERT INTO RequestGeneration_table` (insert new entity)
-ExportController -> MessageQueue: warn about a new request
-activate MessageQueue
-ExportController -> User: "ok, generation is in process"
-deactivate ExportController
-
-note left of User: The user see a waiting screen
-
-MessageQueue -> MessengerConsumer: forward the message to the MessengerConsumer
-deactivate MessageQueue
-activate MessengerConsumer
-MessengerConsumer -> Database: `SELECT * FROM RequestGeneration_table WHERE id = %s`
-activate Database
-Database -> MessengerConsumer: return RequestGeneration with serializedData
-deactivate Database
-
-loop for every ExportElement (Filter, Aggregator)
-    MessengerConsumer -> ExportElement: deserializeData
-    activate ExportElement
-    ExportElement -> MessengerConsumer: return data (list of entities, etc.) from the serialized array
-    deactivate ExportElement
-    MessengerConsumer -> ExportElement: alter the sql query (`ExportElement::alterQuery`)
-    activate ExportElement
-    ExportElement -> MessengerConsumer: return the query with WHERE and GROUP BY clauses
-    deactivate ExportElement
-end
-
-MessengerConsumer -> MessengerConsumer: prepare the export
-MessengerConsumer -> MessengerConsumer: save the export as a stored object
-MessengerConsumer -> Database: `UPDATE RequestGeneration_table SET ready = true`
-deactivate MessengerConsumer
-
-User -> ExportController: pull every 5s to know if the export is generated
-activate ExportController
-ExportController -> User: warn the export is generated
-deactivate ExportController
-
-User -> ExportController: download the export from object storage
-
-
-
-
-
-@enduml

docs/source/development/exports.md

@@ -1,66 +1,49 @@
-.. Copyright (C)  2014 Champs Libres Cooperative SCRLFS
-   Permission is granted to copy, distribute and/or modify this document
-   under the terms of the GNU Free Documentation License, Version 1.3
-   or any later version published by the Free Software Foundation;
-   with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
-   A copy of the license is included in the section entitled "GNU
-   Free Documentation License".
-
-
-Exports
-*******
+###### Exports
 
 Export is an important issue within the Chill software : users should be able to :
 
 - compute statistics about their activity ;
 - list "things" which are a part of their activities.
 
-The `main bundle`_ provides a powerful framework to build custom queries with re-usable parts across differents bundles.
+The [main bundle`_ provides a powerful framework to build custom queries with re-usable parts across differents bundles.
 
-.. contents:: Table of content
    :local:
 
-.. seealso::
-
-   `The issue where this framework was discussed <https://git.framasoft.org/Chill-project/Chill-Main/issues/9>`_
+   `The issue where this framework was [discussed](https://git.framasoft.org/Chill-project/Chill-Main/issues/9)
       Provides some information about the pursued features and architecture.
 
-Concepts
-========
+## Concepts
 
-
-Some vocabulary: 3 "Export elements"
-------------------------------------
+### Some vocabulary: 3 "Export elements"
 
 Four terms are used for this framework :
 
 Exports
    provide some basic operation on the data. Two kinds of exports are available :
 
-   - computed data : it may be "the number of people", "the number of activities", "the duration of activities", ...
-   - list data : it may be "the list of people", "the list of activities", ...
+   - computed data: it may be "the number of people," "the number of activities," "the duration of activities," ...
+   - list data: it may be "the list of people," "the list of activities," ...
 
 Filters
    The filters create a filter on the data: it removes some information the user doesn't want to introduce in the computation done by the export.
 
-   Example of a filter: "people under 18 years olds", "activities between the 1st of June and the 31st December", ...
+   Example of a filter: "people under 18-year-olds," "activities between the 1st of June and the 31st December," ...
 
 Aggregators
    The aggregator aggregates the data into some group (some software use the term 'bucket').
 
-   Example of an aggregator : "group people by gender", "group people by nationality", "group activity by type", ...
+   Example of an aggregator: "group people by gender," "group people by nationality," "group activity by type," ...
 
 Formatters
    The formatters format the data into a :class:`Symfony\Component\HttpFoundation\Response`, which  will be returned "as is" by the controller to the web client.
 
-   Example of a formatter: "format data as CSV", "format data as an ods spreadsheet", ...
+   Example of a formatter: "format data as CSV", "format data as an ods spreadsheet," ...
 
-Anatomy of an export
----------------------
+### Anatomy of an export
 
 An export can be thought of as a sentence where each part of this sentence refers to one or multiple export elements. Examples :
 
-**Example 1**: Count the number of people having at least one activity in the last 12 month, and group them by nationality and gender, and format them in a CSV spreadsheet.
+**Example 1**: Count the number of people having at least one activity in the last month 12, and group them by nationality and gender, and format them in a CSV spreadsheet.
 
 Here :
 
@@ -73,21 +56,16 @@ Here :
 Note that :
 
 - Aggregators, filters, exports and formatters are cross-bundle. Here the bundle *activity* provides a filter which is applied on an export provided by the person bundle ;
-- Multiple aggregator or filter for one export may exist. Currently, only one export is allowed.
+- Multiple aggregators or filters for one export may exist. Currently, only one export is allowed.
 
 The result might be :
 
-+-----------------------+----------------+---------------------------+
-| Nationality           | Gender         | Number of people          |
-+=======================+================+===========================+
-| Russian               | Male           | 12                        |
-+-----------------------+----------------+---------------------------+
-| Russian               | Female         | 24                        |
-+-----------------------+----------------+---------------------------+
-| France                | Male           | 110                       |
-+-----------------------+----------------+---------------------------+
-| France                | Female         | 150                       |
-+-----------------------+----------------+---------------------------+
++-------------+--------+------------------+
+| Nationality | Gender | Number of people |
+| Russian | Male | 12 |
+| Russian | Female | 24 |
+| France | Male | 110 |
+| France | Female| 150 |
 
 **Example 2**: Count the average duration of an activity with type "meeting", which occurs between the 1st of June and the 31st of December, group them by week, and format the data in an OpenDocument spreadsheet.
 
@@ -103,122 +81,97 @@ The result might be :
 
 +-----------------------+----------------------+
 | Week                  | Number of activities |
-+=======================+======================+
 | 2015-10               | 10                   |
-+-----------------------+----------------------+
 | 2015-11               | 12                   |
-+-----------------------+----------------------+
 | 2015-12               | 10                   |
-+-----------------------+----------------------+
 | 2015-13               | 9                    |
-+-----------------------+----------------------+
 
-Authorization and exports
--------------------------
+### Authorization and exports
 
-Exports, filters and aggregators should not show data the user is not allowed to see within the application.
+Exports, filters, and aggregators should not show data the user is not allowed to see within the application.
 
 In other words, developers are required to take care of user authorization for each export.
 
 There should be a specific role that grants permission to users who are allowed to build exports. For more simplicity, this role should apply on a center, and should not require special circles.
 
-How does the magic work ?
-===========================
+## How does the magic work?
 
 To build an export, we rely on the capacity of the database to execute queries with aggregate (i.e. GROUP BY) and filter (i.e. WHERE) instructions.
 
-An export is an SQL query which is initiated by an export, and modified by aggregators and filters.
+An export is an SQL query that is initiated by an export and modified by aggregators and filters.
 
-.. note::
-
-   **Example**: Count the number of people having at least one activity in the last 12 month, and group them by nationality and gender
+   **Example**: Count the number of people having at least one activity in the last month 12, and group them by nationality and gender
 
    1. The report initiates the query
 
-   .. code-block:: SQL
-
+   ```SQL
       SELECT count(people.*) FROM people
+```
 
    2. The filter adds a where and join clause :
 
-   .. code-block:: SQL
-
+   ```SQL
       SELECT count(people.*) FROM people
          RIGHT JOIN activity
          WHERE activity.date IS BETWEEN now AND 6 month ago
+```
 
    3. The aggregator "nationality" adds a GROUP BY clause and a column in the SELECT statement:
 
-   .. code-block:: sql
-
+   ```sql
       SELECT people.nationality, count(people.*) FROM people
          RIGHT JOIN activity
          WHERE activity.date IS BETWEEN now AND 6 month ago
          GROUP BY nationality
+```
 
    4. The aggregator "gender" does the same job as the nationality aggregator : it adds a GROUP BY clause and a column in the SELECT statement :
 
-   .. code-block:: sql
-
+   ```sql
       SELECT people.nationality, people.gender, count(people.*)
          FROM people RIGHT JOIN activity
          WHERE activity.date IS BETWEEN now AND 6 month ago
          GROUP BY nationality, gender
+```
 
-Each filter, aggregator and filter may collect parameters from the user through a form. This form is appended to the export form. Here is an example.
-
-.. figure:: /_static/screenshots/development/export_form-fullpage.png
+Each filter, aggregator, and filter may collect parameters from the user through a form. This form is appended to the export form. Here is an example.
 
    The screenshot shows the export form for ``CountPeople`` (Nombre de personnes). The filter by date of birth is checked (*Filtrer par date de naissance de la personne*), which triggers a subform, which is provided by the :class:`Chill\PersonBundle\Export\Filter\BirthdateFilter`. The other unchecked filter does not show the subform.
 
-   Two aggregators are also checked : by Country of birth (*Aggréger les personnes par pays de naissance*, the corresponding class is :class:`Chill\PersonBundle\Export\Aggregator\CountryOfBirthAggregator`, which also triggers a subform. The aggregator by gender (*Aggréger les personnes par genre*) is also checked, but there is no corresponding subform.
+   Two aggregators are also checked: by Country of birth (*Aggréger les personnes par pays de naissance*, the corresponding class is :class:`Chill\PersonBundle\Export\Aggregator\CountryOfBirthAggregator`, which also triggers a subform. The aggregator by gender (*Aggréger les personnes par genre*) is also checked, but there is no corresponding subform.
 
-The Export Manager
-------------------
+### The Export Manager
 
-The Export manager (:class:`Chill\MainBundle\Export\ExportManager` is the central class which registers all exports, aggregators, filters and formatters.
+The Export manager (:class:`Chill\MainBundle\Export\ExportManager` is the central class which registers all exports, aggregators, filters, and formatters.
 
 The export manager is also responsible for orchestrating the whole export process, producing a :class:`Symfony\FrameworkBundle\HttpFoundation\Request` for each export request.
 
-
-The export form step
---------------------
+### The export form step
 
 The form step allows you to build a form, combining different parts of the module.
 
 The building of forms is split into different subforms, where each one is responsible for rendering their part of the form (aggregators, filters, and export).
 
-.. figure:: /_static/puml/exports/form_steps.png
    :scale: 40%
 
-The formatter form step
------------------------
+### The formatter form step
 
 The formatter form is processed *after* the user filled the export form. It is built the same way, but receives the data entered by the user on the previous step as parameters (i.e. export form). It may then adapt it accordingly (example: show a list of columns selected in aggregators).
 
-Processing the export
----------------------
+### Processing the export
 
-The export process can be explained by this schema :
+This schema can explain the export process :
 
-.. figure:: /_static/puml/exports/processing_export.png
    :scale: 40%
 
    (Click to enlarge)
 
+## Export, formatters, and filters explained
 
-Export, formatters and filters explained
-========================================
-
-Exports
--------
+### Exports
 
 This is an example of the ``CountPerson`` export :
 
-.. literalinclude:: /_static/code/exports/CountPerson.php
-   :language: php
-   :linenos:
-
 * **Line 36**: the ``getType`` function returns a string. This string will be used to find the aggregtors and filters which will apply to this export.
 * **Line 41**: a simple description to help users understand what your export does.
 * **Line 46**: The title of the export. A summary of what your export does.
@@ -226,26 +179,17 @@ This is an example of the ``CountPerson`` export :
 * **Line 56**: We initiate the query here...
 * **Line 59**: We have to filter the query with centers the users checked in the form. We process the $acl variable to get all ``Center`` objects in one array
 * **Line 63**: We create the query with a query builder.
-* **Line 74**: We return the result, but make sure to hydrate the results as an array.
+* **Line 74**: We return the result but make sure to hydrate the results as an array.
 * **Line 103**: return the list of formatter types which are allowed to be applied on this filter
 
-Filters
--------
+### Filters
 
-This is an example of the *filter by birthdate*. This filter asks some information through a form (`buildForm` is not empty), and this form must be validated. To perform this validation, we implement a new Interface: :class:`Chill\MainBundle\Export\ExportElementValidatedInterface`:
-
-.. literalinclude:: /_static/code/exports/BirthdateFilter.php
-   :language: php
-
-.. todo::
+This is an example of the *filter by birthdate*. This filter asks some information through a form (`buildForm` is not empty), and this form must be validated. To perform this validation, we implement a new Interface: `Chill\MainBundle\Export\ExportElementValidatedInterface`:
 
    Continue to explain the export framework
 
-.. _main bundle: https://git.framasoft.org/Chill-project/Chill-Main
-
-
-With many-to-* relationship, why should we set WHERE clauses in an EXISTS subquery instead of a JOIN ?
-``````````````````````````````````````````````````````````````````````````````````````````````````````
+With many-to-* relationship, why should we set WHERE clauses in an EXISTS subquery instead of a JOIN?
+-----------------------------------------------------------------------------------------------------
 
 As we described above, the doctrine builder is converted into a sql query. Let's see how to compute the "number of course
 which count at least one activity type with the id 7". For the purpose of this demonstration, we will restrict this on
@@ -253,79 +197,65 @@ two accompanying period only: the ones with id 329 and 334.
 
 Let's see the list of activities associated with those accompanying period:
 
-.. code-block:: sql
-
    SELECT id, accompanyingperiod_id, type_id FROM activity WHERE accompanyingperiod_id IN (329, 334) AND type_id = 7
        ORDER BY accompanyingperiod_id;
 
 We see that we have 6 activities for the accompanying period with id 329, and only one for the 334's one.
 
-.. csv-table::
-   :header: id, accompanyingperiod_id, type_id
-
-   990,329,7
-   986,329,7
-   987,329,7
-   993,329,7
-   991,329,7
-   992,329,7
-   1000,334,7
+| id   | accompanyingperiod_id | type_id |
+|------|----------------------|---------|
+| 990  | 329                  | 7       |
+| 986  | 329                  | 7       |
+| 987  | 329                  | 7       |
+| 993  | 329                  | 7       |
+| 991  | 329                  | 7       |
+| 992  | 329                  | 7       |
+| 1000 | 334                  | 7       |
 
 Let's calculate the average duration for those accompanying periods, and the number of period:
 
-.. code-block:: sql
-
    SELECT AVG(age(COALESCE(closingdate, CURRENT_DATE), openingdate)), COUNT(id) from chill_person_accompanying_period WHERE id IN (329, 334);
 
 The result of this query is:
 
-.. csv-table::
-   :header: AVG, COUNT
+| AVG                                              | COUNT |
+|--------------------------------------------------|-------|
+| 2 years 2 mons 21 days 12 hours 0 mins 0.0 secs | 2     |
 
-   2 years 2 mons 21 days 12 hours 0 mins 0.0 secs,2
-
-Now, we count the number of accompanying period, adding a :code:`JOIN` clause which make a link to the :code:`activity` table, and add a :code:`WHERE` clause to keep
+Now, we count the number of accompanying period, adding a `JOIN` clause which make a link to the `activity` table, and add a `WHERE` clause to keep
 only the accompanying period which contains the given activity type:
 
-.. code-block:: sql
-
    SELECT COUNT(chill_person_accompanying_period.id) from chill_person_accompanying_period
                  JOIN activity ON chill_person_accompanying_period.id = activity.accompanyingperiod_id
                  WHERE chill_person_accompanying_period.id IN (329, 334) AND activity.type_id = 7;
 
-What are the results here ?
+What are the results here?
 
-.. csv-table::
-   :header: COUNT
+| COUNT |
+|-------|
+| 7     |
 
-   7
-
-:code:`7` ! Why this result ? Because the number of lines is duplicated for each activity. Let's see the list of rows which
+`7` ! Why this result? Because the number of lines is duplicated for each activity. Let's see the list of rows which
 are taken into account for the computation:
 
-.. code-block:: sql
-
    SELECT chill_person_accompanying_period.id, activity.id from chill_person_accompanying_period
    JOIN activity ON chill_person_accompanying_period.id = activity.accompanyingperiod_id
    WHERE chill_person_accompanying_period.id IN (329, 334) AND activity.type_id = 7;
 
-.. csv-table::
-   :header: accompanyingperiod.id, activity.id
+| accompanyingperiod.id | activity.id |
+|----------------------|-------------|
+| 329                  | 993         |
+| 334                  | 1000        |
+| 329                  | 987         |
+| 329                  | 990         |
+| 329                  | 991         |
+| 329                  | 992         |
+| 329                  | 986         |
 
-   329,993
-   334,1000
-   329,987
-   329,990
-   329,991
-   329,992
-   329,986
-
-For each activity, a row is created and, as we count the number of non-null :code:`accompanyingperiod.id` columns, we
+For each activity, a row is created and, as we count the number of non-null `accompanyingperiod.id` columns, we
 count one entry for each activity (actually, we count the number of activities).
 
-So, let's use the :code:`DISTINCT` keyword to count only once the equal ids:
-
-.. code-block::
+So, let's use the `DISTINCT` keyword to count only once the equal ids:
 
    SELECT COUNT(DISTINCT chill_person_accompanying_period.id) from chill_person_accompanying_period
    JOIN activity ON chill_person_accompanying_period.id = activity.accompanyingperiod_id
@@ -333,38 +263,31 @@ So, let's use the :code:`DISTINCT` keyword to count only once the equal ids:
 
 Now, it works again...
 
-.. csv-table::
-   :header: COUNT
+| COUNT |
+|-------|
+| 2     |
 
-   2
+But, for the average duration, this won't work: the duration which are equals (because the `openingdate` is the same and
+`closingdate` is still `NULL`, for instance) will be counted only once, which will give unexpected result.
 
-But, for the average duration, this won't work: the duration which are equals (because the :code:`openingdate` is the same and
-:code:`closingdate` is still :code:`NULL`, for instance) will be counted only once, which will give unexpected result.
-
-The solution is to move the condition "having an activity with activity type with id 7" in a :code:`EXISTS` clause:
-
-.. code-block:: sql
+The solution is to move the condition "having an activity with activity type with id 7" in a `EXISTS` clause:
 
    SELECT COUNT(chill_person_accompanying_period.id) from chill_person_accompanying_period
    WHERE chill_person_accompanying_period.id IN (329, 334) AND EXISTS (SELECT 1 FROM activity WHERE type_id = 7 AND accompanyingperiod_id = chill_person_accompanying_period.id);
 
-The result is correct without :code:`DISTINCT` keyword:
+The result is correct without `DISTINCT` keyword:
 
-.. csv-table::
-   :header: COUNT
-
-   2
+| COUNT |
+|-------|
+| 2     |
 
 And we can now compute the average duration without fear:
 
-.. code-block:: sql
-
   SELECT AVG(age(COALESCE(closingdate, CURRENT_DATE), openingdate)) from chill_person_accompanying_period
   WHERE chill_person_accompanying_period.id IN (329, 334) AND EXISTS (SELECT 1 FROM activity WHERE type_id = 7 AND accompanyingperiod_id = chill_person_accompanying_period.id);
 
 Give the result:
 
-.. csv-table::
-   :header: AVG
-
-   2 years 2 mons 21 days 12 hours 0 mins 0.0 secs
+| AVG                                              |
+|--------------------------------------------------|
+| 2 years 2 mons 21 days 12 hours 0 mins 0.0 secs |

docs/source/development/forms.md

@@ -0,0 +1,25 @@
+# Forms and form types
+
+###### Date picker
+
+Class
+   `Chill\MainBundle\Form\Type\ChillDateType`
+Extend
+   `Symfony\Component\Form\Extension\Core\Type\DateType`
+
+Usage :
+
+```
+   use Chill\MainBundle\Form\Type\ChillDateType;
+
+   $builder->add('date' ChillDateType::class);
+```
+
+###### Text editor
+
+Add a text editor (by default).
+
+Class
+   `Chill\MainBundle\Form\Type\ChillTextareaType`
+Options
+   * `disable_editor` to disable text editor

docs/source/development/forms.rst

@@ -1,42 +0,0 @@
-
-.. Copyright (C)  2014 Champs Libres Cooperative SCRLFS
-   Permission is granted to copy, distribute and/or modify this document
-   under the terms of the GNU Free Documentation License, Version 1.3
-   or any later version published by the Free Software Foundation;
-   with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
-   A copy of the license is included in the section entitled "GNU
-   Free Documentation License".
-
-.. _forms:
-
-Forms and form types
-####################
-
-Date picker
-***********
-
-Class
-   :class:`Chill\MainBundle\Form\Type\ChillDateType`
-Extend
-   :class:`Symfony\Component\Form\Extension\Core\Type\DateType`
-
-
-Usage :
-
-.. code-block:: php
-
-   use Chill\MainBundle\Form\Type\ChillDateType;
-
-   $builder->add('date' ChillDateType::class);
-
-Text editor
-***********
-
-Add a text editor (by default).
-
-Class
-   :class:`Chill\MainBundle\Form\Type\ChillTextareaType`
-Options
-   * :code:`disable_editor` to disable text editor
-
-

docs/source/development/index.md

@@ -0,0 +1,41 @@
+# Development
+
+As Chill relies on the [symfony ](http://symfony.com) framework, reading the framework's documentation should answer most of your questions. We are explaining here some tips to work with Chill, and help with things we've encountered.
+
+- [Instructions to create a new bundle](create-a-new-bundle.md)
+- [CRUD (Create - Update - Delete) for one entity](crud.md)
+- [Helpers for building a REST API](api.md)
+- [Routing](routing.md)
+- [Menus](menus.md)
+- [Forms](forms.md)
+- [Access control model](access_control_model.md)
+- [Messages to users](messages-to-users.md)
+- [Pagination](pagination.md)
+- [Localisation](localisation.md)
+- [Logging](logging.md)
+- [Database migrations](migrations.md)
+- [Searching](searching.md)
+- [Timelines](timelines.md)
+- [Exports](exports.md)
+- [Embeddable comments](embeddable-comments.md)
+- [Run tests](run-tests.md)
+- [ESLint](es-lint.md)
+- [Useful snippets](useful-snippets.md)
+- [Manual](manual/index.md)
+- [Assets](assets.md)
+- [Cron Jobs](cronjob.md)
+- [Info about entities](entity-info.md)
+- [Info about database (in French)](database-principles.md)
+- [Developer FAQ](FAQ.md)
+
+###### Layout and UI
+
+- [Render entities automatically](render-entity.md)
+- [Layout / Template usage](user-interface/layout-template-usage.md)
+- [Classes and mixins](user-interface/css-classes.md)
+- [Widgets](user-interface/widgets.md)
+- [Javascript function](user-interface/js-functions.md)
+
+###### Help, I am lost!
+
+Write an email at info@champs-libres.coop, and we will help you!

docs/source/development/index.rst

@@ -1,59 +0,0 @@
-.. Copyright (C)  2014 Champs Libres Cooperative SCRLFS
-   Permission is granted to copy, distribute and/or modify this document
-   under the terms of the GNU Free Documentation License, Version 1.3
-   or any later version published by the Free Software Foundation;
-   with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
-   A copy of the license is included in the section entitled "GNU
-   Free Documentation License".
-
-Development
-###########
-
-As Chill relies on the `symfony <http://symfony.com>`_ framework, reading the framework's documentation should answer most of your questions. We are explaining here some tips to work with Chill, and help with things we've encountered.
-
-.. toctree::
-    :maxdepth: 2
-
-    Instructions to create a new bundle <create-a-new-bundle.rst>
-    CRUD (Create - Update - Delete) for one entity <crud.rst>
-    Helpers for building a REST API <api.rst>
-    Routing <routing.rst>
-    Menus <menus.rst>
-    Forms <forms.rst>
-    Access control model <access_control_model.rst>
-    Messages to users <messages-to-users.rst>
-    Pagination <pagination.rst>
-    Localisation <localisation.rst>
-    Logging <logging.rst>
-    Database migrations <migrations.rst>
-    Searching <searching.rst>
-    Timelines <timelines.rst>
-    Exports <exports.rst>
-    Embeddable comments <embeddable-comments.rst>
-    Run tests <run-tests.rst>
-    ESLint <es-lint.rst>
-    Useful snippets <useful-snippets.rst>
-    manual/index.rst
-    Assets <assets.rst>
-    Cron Jobs <cronjob.rst>
-    Info about entities <entity-info.rst>
-    Info about database (in French) <database-principles.rst>
-    Developer FAQ <FAQ.rst>
-
-Layout and UI
-**************
-
-.. toctree::
-   :maxdepth: 2
-
-   Render entities automatically <render-entity.rst>
-   Layout / Template usage <user-interface/layout-template-usage.rst>
-   Classes and mixins <user-interface/css-classes.rst>
-   Widgets <user-interface/widgets.rst>
-   Javascript function <user-interface/js-functions.rst>
-
-
-Help, I am lost !
-*****************
-
-Write an email at info@champs-libres.coop, and we will help you !

docs/source/development/localisation.md

@@ -0,0 +1,30 @@
+###### Localisation
+
+## Language in url
+
+Language should be present in URL, conventionally as the first argument.
+
+   `/fr/your/url/here`
+
+This allows users to change from one language to another one on each page, which may be useful in multilanguages teams. If the installation is single-language, the language switcher will not appears.
+
+This is an example of routing defined in YAML :
+
+```yaml
+   chill_person_general_edit:
+       pattern: /{_locale}/person/{person_id}/general/edit
+       defaults: {_controller: ChillPersonBundle:Person:edit }
+```
+
+## Date and time
+
+The [Intl extension ](http://twig.sensiolabs.org/doc/extensions/intl.html) is enabled on the Chill application.
+
+You may format date and time using the [localizeddate` function :
+
+   `date|localizeddate('long', 'none')`
+
+By default, we prefer using the `long` format for date formatting.
+
+   [Documentation for Intl Extension](http://twig.sensiolabs.org/doc/extensions/intl.html)
+      Read the complete doc for the Intl extension.

docs/source/development/localisation.rst

@@ -1,49 +0,0 @@
-.. Copyright (C)  2014 Champs Libres Cooperative SCRLFS
-   Permission is granted to copy, distribute and/or modify this document
-   under the terms of the GNU Free Documentation License, Version 1.3
-   or any later version published by the Free Software Foundation;
-   with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
-   A copy of the license is included in the section entitled "GNU
-   Free Documentation License".
-
-Localisation
-*************
-
-Language in url
-===============
-
-Language should be present in URL, conventionnaly as first argument. 
-
-.. code-block:: none
-
-   /fr/your/url/here
-
-This allow users to change from one language to another one on each page, which may be useful in multilanguages teams. If the installation is single-language, the language switcher will not appears.
-
-This is an example of routing defined in yaml : 
-
-.. code-block:: yaml
-
-   chill_person_general_edit:
-       pattern: /{_locale}/person/{person_id}/general/edit
-       defaults: {_controller: ChillPersonBundle:Person:edit }
-
-
-Date and time
-==============
-
-The `Intl extension <http://twig.sensiolabs.org/doc/extensions/intl.html>`_ is enabled on the Chill application. 
-
-You may format date and time using the `localizeddate` function : 
-
-.. code-block:: jinja
-
-   date|localizeddate('long', 'none')
-
-By default, we prefer using the `long` format for date formatting.
-
-.. seealso::
-
-   `Documentation for Intl Extension <http://twig.sensiolabs.org/doc/extensions/intl.html>`_
-      Read the complete doc for the Intl extension.
-   

docs/source/development/logging.md

@@ -1,50 +1,41 @@
-.. Copyright (C)  2016 Champs Libres Cooperative SCRLFS
-   Permission is granted to copy, distribute and/or modify this document
+Permission is granted to copy, distribute and/or modify this document
    under the terms of the GNU Free Documentation License, Version 1.3
    or any later version published by the Free Software Foundation;
    with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
    A copy of the license is included in the section entitled "GNU
    Free Documentation License".
 
+###### Logging
 
-Logging
-*******
 
-.. seealso::
-   
-   Symfony documentation: `How to user Monolog to write logs <http://symfony.com/doc/current/cookbook/logging/monolog.html>`_
+   Symfony documentation: [How to user Monolog to write logs ](http://symfony.com/doc/current/cookbook/logging/monolog.html)
       The symfony cookbook page about logging.
 
+A channel for custom logging has been created to store sensitive data.
 
-A channel for custom logging has been created to store sensitive data. 
-
-The channel is named ``chill``. 
+The channel is named ``chill``.
 
 The installer of chill should be aware that this channel may contains sensitive data and encrypted during backup.
 
-Logging to channel `chill`
-============================
+## Logging to channel `chill`
 
-You should use the service named ``chill.main.logger``, as this : 
+You should use the service named ``chill.main.logger``, as this :
 
-.. code-block:: php
+   `$logger = $this->get('chill.main.logger');`
 
-   $logger = $this->get('chill.main.logger');
+You should store data into context, not in the log himself, which should remains the same for the action.
 
-You should store data into context, not in the log himself, which should remains the same for the action. 
-
-Example of usage : 
-
-.. code-block:: php
+Example of usage :
 
+```php
    $logger->info("An action has been performed about a person", array(
       'person_lastname' => $person->getLastName(),
       'person_firstname' => $person->getFirstName(),
       'person_id' => $person->getId(),
       'by_user' => $user->getUsername()
    ));
+```
 
 For further processing, it is a good idea to separate all fields (like firstname, lastname, ...) into different context keys.
 
 By convention, you should store the username of the user performing the action under the ``by_user`` key.
-

docs/source/development/manual/index.md

@@ -1,17 +1,10 @@
-.. Copyright (C)  2014 Champs Libres Cooperative SCRLFS
-   Permission is granted to copy, distribute and/or modify this document
+Permission is granted to copy, distribute and/or modify this document
    under the terms of the GNU Free Documentation License, Version 1.3
    or any later version published by the Free Software Foundation;
    with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
    A copy of the license is included in the section entitled "GNU
    Free Documentation License".
 
-Developer manual
-*****************
-
-.. toctree::
-   :maxdepth: 2
-
-   routing-and-menus.rst
-
+###### Developer manual
 
+- [Routing and Menus](routing-and-menus.md)

docs/source/development/manual/routing-and-menus.md

@@ -1,143 +1,103 @@
-.. Copyright (C)  2014 Champs Libres Cooperative SCRLFS
-   Permission is granted to copy, distribute and/or modify this document
-   under the terms of the GNU Free Documentation License, Version 1.3
-   or any later version published by the Free Software Foundation;
-   with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
-   A copy of the license is included in the section entitled "GNU
-   Free Documentation License".
+###### Routing and menus
 
-Routing and menus
-*****************
-
-
-The *Chill*'s architecture allows to choose bundle on each installation. This may lead to a huge diversity of installations, and a the developper challenge is to make his code working with all those possibles installations.
+The architecture of *Chill* allows choosing a bundle on each installation. This may lead to a huge diversity of installations, and the developper challenge is to make his code work with all those possibles installations.
 
 *Chill* uses menus to let users access easily to the most used functionalities. For instance, when you land on a "Person" page, you may access directly to his activities, notes, documents, ... in a single click on a side menu.
 
 For a developer, it is easy to extend this menu with his own entries.
 
-.. seealso::
-
-   `Symfony documentation about routing <http://symfony.com/doc/current/book/routing.html>`_
+   [Symfony documentation about routing ](http://symfony.com/doc/current/book/routing.html)
       This documentation should be read before diving into those lines
 
-   `Routes dans Chill <https://redmine.champs-libres.coop/issues/179>`_ (FR)
+   [Routes dans Chill ](https://redmine.champs-libres.coop/issues/179) (FR)
       The issue where we discussed routes. In French.
 
-Create routes 
-==============
+## Create routes
 
-.. note::
+   We recommend using `yaml` to define routes. We have not tested the existing other ways to create routes (annotations, ...). Help wanted.
 
-   We recommand using `yaml` to define routes. We have not tested the existing other ways to create routes (annotations, ...). Help wanted.
-
-The first step is as easy as create a route in symfony, and add some options in his description :
-
-.. code-block:: yaml
+The first step is as easy as creating a route in symfony, and add some options in his description :
 
+```yaml
+#src/CL/ChillBundle/Resources/config/routing.yml
    chill_main_dummy_0:
        pattern: /dummy/{personId}
        defaults: { _controller: CLChillMainBundle:Default:index }
        options:
            #we begin menu information here :
-           menus: 
-               foo: #must appears in menu named 'foo'
+           menus:
+               foo: #must appear in a menu named 'foo'
                    order: 500  #the order will be '500'
-                   label: foolabel #the label shown on menu. Will be translated
-                   otherkey: othervalue #you may add other informations, as needed by your layout
-               bar: #must also appears in menu named 'bar'
+                   label: foolabel #the label shown on a menu. Will be translated
+                   otherkey: othervalue #you may add other information, as needed by your layout
+               bar: #must also appear in a menu named 'bar'
                    order: 500
                    label: barlabel
+```
 
-The mandatory parameters under the `menus` definition are : 
+The mandatory parameters under the `menus` definition are :
 
-* `name`: the menu's name, defined as an key for the following entries
-* `order`. Note: if we have duplicate order's values, the order will be incremented. We recommand using big intervals within orders and publishing the orders in your documentation
-* `label`: the text which will be rendered inside the `<a>` tag. The label should be processed trough the `trans` filter (`{{ route.label|trans }}`)
+* `name`: the menu's name, defined as a key for the following entries
+* `order`. Note: if we have duplicate order's values, the order will be incremented. We recommend using big intervals within orders and publishing the orders in your documentation
+* `label`: the text which will be rendered inside the `<a>[ tag. The label should be processed trough the `trans` filter (`{{ route.label|trans }}`)
 
-You *may* also add other keys, which will be used optionally in the way the menu is rendered. See 
+You *may* also add other keys, which will be used optionally in the way the menu is rendered. See
 
-.. warning::
+   Although all keys will be kept from your `yaml` definition to your menu template, we recommend not using those keys, which are reserved for a future implementations of Chill :
 
-   Although all keys will be kept from your `yaml` definition to your menu template, we recommend not using those keys, which are reserved for a future implementations of Chill : 
+   * `helper`, a text to help user or add more information to him
+   * `access` : which will run a test with `Expression Langage ](http://symfony.com/doc/current/components/expression_language/index.html) to determine if the user has the ACL to show the menu entry ;
+   * `condition`, which will test with the menu context if the entry must appear
 
-   * `helper`, a text to help user or add more informations to him
-   * `access` : which will run a test with `Expression Langage <http://symfony.com/doc/current/components/expression_language/index.html>`_ to determine if the user has the ACL to show the menu entry ;
-   * `condition`, which will test with the menu context if the entry must appears
-
-Show menu in twig templates
-===========================
+## Show menu in twig templates
 
 To show our previous menu in the twig template, we invoke the `chill_menu` function. This will render the `foo` menu :
 
-.. code-block:: jinja
+   `{{ chill_menu('foo') }}`
 
-   {{ chill_menu('foo') }}
-
-Passing variables
-^^^^^^^^^^^^^^^^^
+##### Passing variables
 
 If your routes need arguments, i.e. an entity id, you should pass the as argument to the chill_menu function. If your route's pattern is `/person/{personId}`, your code become :
 
-.. code-block:: jinja
-
-   {{ chill_menu('foo', { 'args' : { 'personId' : person.id } } ) }}
+   `{{ chill_menu('foo', { 'args' : { 'personId' : person.id } } ) }}`
 
 Of course, `person` is a variable you must define in your code, which should have an `id` accessible property (i.e. : `$person->getId()`).
 
-.. note::
-
    Be aware that your arguments will be passed to all routes in a menu. If a route does not require `personId` in his pattern, the route will become `/pattern?personId=XYZ`. This should not cause problem in your application.
 
-.. warning::
-
-   It is a good idea to reuse the same parameter's name in your pattern, to avoid collision. Prefer `/person/{personId}` to `/person/{id}`. 
+   It is a good idea to reuse the same parameter's name in your pattern, to avoid collision. Prefer `/person/{personId}` to `/person/{id}`.
 
    If you don't do that and another developer create a bundle with  `person/{personId}/{id}` where `{id}` is the key for something else, this will cause a lot of trouble...
 
-Rendering active entry
-^^^^^^^^^^^^^^^^^^^^^^
+##### Rendering active entry
 
-Now, you want to render differently the *active* route of the menu [#f1]_. You should, in your controller or template, add the active route in your menu : 
+Now, you want to render differently the *active* route of the menu [#f1]_. You should, in your controller or template, add the active route in your menu :
 
-.. code-block:: jinja
-
-   {{ chill_menu('foo', { 'activeRouteKey' : 'chill_main_dummy_0' } ) }}
+   `{{ chill_menu('foo', { 'activeRouteKey' : 'chill_main_dummy_0' } ) }}`
 
 On menu creation, the route wich has the key `chill_main_dummy_0` will be rendered on a different manner.
 
-Define your own template
--------------------------
+### Define your own template
 
 By default, the menu is rendered with the default template, which is a simple `ul` list. You may create your own templates :
 
-.. code-block:: html+jinja
-
+```
    #MyBundle/Resources/views/Menu/MyMenu.html.twig
    <ul class="myMenu">
    {% for route in routes %}
        <li><a href="{{ path(route.key, args ) }}" class="{%- if activeRouteKey == route.key -%}active{%- endif -%}">{{ route.label|trans }}</a></li>
    {% endfor %}
    </ul>
+```
 
 Arguments available in your template :
 
 * The `args` value are the value passed in the 'args' arguments requested by the `chill_menu` function.
-* `activeRouteKey` is the key of the currently active route. 
+* `activeRouteKey` is the key of the currently active route.
 * `routes` is an array of routes. The array has this structure: `routes[order] = { 'key' : 'the_route_key', 'label' : 'the route label' }` The order is *resolved*: in case of collision (two routes from different bundles having the same order), the order will be incremented. You may find in the array your own keys (`{ 'otherkey' : 'othervalue'}` in the example above).
 
 Then, you will call your own template with the `layout` argument :
 
-.. code-block:: jinja
-
-   {{ chill_menu('foo', { 'layout' : 'MyBundle:Menu:MyMenu.html.twig' } ) }}
-
-.. note::
+   `{{ chill_menu('foo', { 'layout' : 'MyBundle:Menu:MyMenu.html.twig' } ) }}`
 
    Take care of specifying the absolute path to layout in the function.
-
-
-
-.. rubric:: Footnotes
-
-.. [#f1] In the default template, the currently active entry will be rendered with an "active" class : `<li class="active"> ... </li>`

docs/source/development/menus.md

@@ -1,44 +1,25 @@
-.. Copyright (C)  2014 Champs Libres Cooperative SCRLFS
-   Permission is granted to copy, distribute and/or modify this document
-   under the terms of the GNU Free Documentation License, Version 1.3
-   or any later version published by the Free Software Foundation;
-   with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
-   A copy of the license is included in the section entitled "GNU
-   Free Documentation License".
-
-.. _menus :
-
-Menus
-*****
+###### Menus
 
 Chill has created his own menu system
 
-.. seealso::
-
-   `Routes dans Chill [specification] <https://redmine.champs-libres.coop/issues/179>`_
+   [Routes dans Chill [specification] ](https://redmine.champs-libres.coop/issues/179)
        The issue wich discussed the implementation of routes.
 
-Concepts
-========
-
-.. warning:: 
+## Concepts
 
    to be written
 
-
-
-Add a menu in a template
-========================
+## Add a menu in a template
 
 In your twig template, use the `chill_menu` function :
 
-.. code-block:: html+jinja
-
+```php
    {{ chill_menu('person', {
 	     'layout': 'ChillPersonBundle::menu.html.twig',
-	     'args' : {'id': person.id },
+	     'args': {'id': person.id },
 	     'activeRouteKey': 'chill_person_view'
 	}) }}
+```
 
 The available arguments are:
 
@@ -46,78 +27,61 @@ The available arguments are:
 * `args` : those arguments will be passed through the url generator.
 * `activeRouteKey` must be the route key name.
 
-.. note:: 
-
    The argument `activeRouteKey` may be a twig variable, defined elsewhere in your template, even in child templates.
 
-
-
-Create an entry in an existing menu
-===================================
+## Create an entry in an existing menu
 
 If a route belongs to a menu, you simply add this to his definition in routing.yml :
 
-.. code-block:: yaml
-
+```yaml
    chill_person_history_list:
        pattern: /person/{person_id}/history
        defaults: { _controller: ChillPersonBundle:History:list }
        options:
            #declare menus
-           menus: 
-               # the route should be in 'person' menu : 
+           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.**
+* `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 :
 
-.. code-block:: yaml
-
+```yaml
    chill_person_history_list:
        pattern: /person/{person_id}/history
        defaults: { _controller: ChillPersonBundle:History:list }
        options:
-           menus: 
+           menus:
                menu1:
                    order: 100
                    label: menu.person.history
                menu2:
                    order: 100
                    label: another.label
+```
 
-
-
-Customize menu rendering
-========================
+## Customize menu rendering
 
 You may customize menu rendering by using the `layout` option.
 
-.. warning ::
-   
-   TODO : this part should be written.
 
+   TODO: this part should be written.
 
-
-
-
-
-.. _caveats :
-
-Caveats
-=======
+## 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 menu declaration in twig template
+* 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`)

docs/source/development/messages-to-users.md

@@ -0,0 +1,93 @@
+###### Messages to users, flashbags, and buttons
+
+## Flashbags
+
+The four following levels are defined :
+
++-----------+----------------------------------------------------------------------------------------------+
+|Key|Intent |
+|success|The user action succeeds.                                                                     |
+|notice|A simple message to give information to the user. The message may be linked or not linked with |
+||the user action.                                                                              |
+|error|The user's action failed: he must correct something to process the action.                    |
+
+We can use [TranslatableMessage` (and other `TranslatableMessageInterface` instances) into the controller:
+
+```php
+   // in a controller action:
+   if (($session = $request->getSession()) instanceof Session) {
+       $session->getFlashBag()->add(
+           'success',
+           new TranslatableMessage('saved_export.Saved export is saved!')
+       );
+   }
+```
+
+   `Flash Messages on Symfony documentation ](http://symfony.com/doc/current/book/controller.html#flash-messages)
+      Learn how to use flash messages in a controller.
+
+## Buttons
+
+Some actions are available to decorate ``a`` links and ``buttons``.
+
+To add the action on button, use them as class along with ``sc-button`` :
+
+   <a class="sc-button bt-create">Create an entity</a>
+
+   <button class="sc-button bt-submit" type="submit">Submit</button>
+
++-----------+----------------+------------------------------------------------------------------------------+
+| Action    |  Class         | Description                                                                  |
+| Submit    | ``bt-submit``  | Submit a form. Use only if the action is not "save."                             |
+| Create    | ``bt-create``  | - Link to a form to create an entity (alias: ``bt-new``)                     |
+|           | or ``bt-new``  | - Submitting this form will create a new entity                              |
+| Reset     | ``bt-reset``   | Reset a form                                                                 |
+| Delete    | ``bt-delete``  | - Link to a form to delete an entity                                         |
+|           |                | - Submitting this form will remove the entity                                |
+| Edit      | ``bt-edit`` or | Link to a form to edit an entity                                             |
+|           | ``bt-update``  |                                                                              |
+| Save      | ``bt-save``    | Submitting this form will save change on the entity                          |
+| Action    | ``bt-action``  | Generic link to an action                                                    |
+| Cancel    | ``bt-cancel``  | Cancel an action and go back to another page                                 |
+
+### Styling buttons
+
+Small buttons, mainly to use inline
+
+   `<p><a class="sc-button bt-create bt-small">You button</a></p>`
+
+You can omit content and show a button with an icon only :
+
+   `<a class="sc-button bt-create"></a>`
+
+You can hide content and show it only on hover
+
+   `<a class="sc-button bt-create has-hidden"><span class="show-on-hover">Showed when mouse pass on</span></a>`
+
+You can customize the icon :
+
+  `<a class="sc-button bt-create change-icon"><i class="fa fa-icon"></i>Button with custom icon</a>`
+
+### Grouping buttons
+
+Grouping buttons can be done using ``ul.record_actions`` element (an ``ul`` list with class ``record_actions``):
+
+```html
+   <ul class="record_actions">
+
+      <li class="cancel">
+         <a class="sc-button bt-cancel">Cancel</a>
+      <li>
+
+      <li>
+         <a class="sc-button bt-save">Save</a>
+      </li>
+
+   </ul>
+```
+
+The element with the ``cancel`` class will be set in first position.
+
+Inside the table, the space between elements will be shorter.
+
+You can add the class ``record_actions_small`` if you want shorter space between elements.

docs/source/development/messages-to-users.rst

@@ -1,136 +0,0 @@
-.. Copyright (C)  2014 Champs Libres Cooperative SCRLFS
-   Permission is granted to copy, distribute and/or modify this document
-   under the terms of the GNU Free Documentation License, Version 1.3
-   or any later version published by the Free Software Foundation;
-   with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
-   A copy of the license is included in the section entitled "GNU
-   Free Documentation License".
-
-Messages to users, flashbags and buttons
-****************************************
-
-
-.. _flashbags :
-
-Flashbags
-==========
-
-The four following levels are defined :
-
-+-----------+----------------------------------------------------------------------------------------------+
-|Key        |Intent                                                                                        |
-+===========+==============================================================================================+
-|success    |The user action succeeds.                                                                     |
-+-----------+----------------------------------------------------------------------------------------------+
-|notice     |A simple message to give information to the user. The message may be linked or not linked with|
-|           |the user action.                                                                              |
-+-----------+----------------------------------------------------------------------------------------------+
-|error      |The user's action failed: he must correct something to process the action.                    |
-+-----------+----------------------------------------------------------------------------------------------+
-
-We can use :code:`TranslatableMessage` (and other :code:`TranslatableMessageInterface` instances) into the controller:
-
-.. code-block:: php
-
-   // in a controller action:
-   if (($session = $request->getSession()) instanceof Session) {
-       $session->getFlashBag()->add(
-           'success',
-           new TranslatableMessage('saved_export.Saved export is saved!')
-       );
-   }
-
-.. seealso::
-
-   `Flash Messages on Symfony documentation <http://symfony.com/doc/current/book/controller.html#flash-messages>`_
-      Learn how to use flash messages in controller.
-
-
-Buttons
-========
-
-Some actions are available to decorate ``a`` links and ``buttons``.
-
-To add the action on button, use them as class along with ``sc-button`` :
-
-.. code-block:: html
-
-   <a class="sc-button bt-create">Create an entity</a>
-
-   <button class="sc-button bt-submit" type="submit">Submit</button>
-
-+-----------+----------------+------------------------------------------------------------------------------+
-| Action    |  Class         | Description                                                                  |
-+===========+================+==============================================================================+
-| Submit    | ``bt-submit``  | Submit a form. Use only if action is not "save".                             |
-+-----------+----------------+------------------------------------------------------------------------------+
-| Create    | ``bt-create``  | - Link to a form to create an entity (alias: ``bt-new``)                     |
-|           | or ``bt-new``  | - Submitting this form will create a new entity                              |
-+-----------+----------------+------------------------------------------------------------------------------+
-| Reset     | ``bt-reset``   | Reset a form                                                                 |
-+-----------+----------------+------------------------------------------------------------------------------+
-| Delete    | ``bt-delete``  | - Link to a form to delete an entity                                         |
-|           |                | - Submitting this form will remove the entity                                |
-+-----------+----------------+------------------------------------------------------------------------------+
-| Edit      | ``bt-edit`` or | Link to a form to edit an entity                                             |
-|           | ``bt-update``  |                                                                              |
-+-----------+----------------+------------------------------------------------------------------------------+
-| Save      | ``bt-save``    | Submitting this form will save change on the entity                          |
-+-----------+----------------+------------------------------------------------------------------------------+
-| Action    | ``bt-action``  | Generic link to an action                                                    |
-+-----------+----------------+------------------------------------------------------------------------------+
-| Cancel    | ``bt-cancel``  | Cancel an action and go back to another page                                 |
-+-----------+----------------+------------------------------------------------------------------------------+
-
-Styling buttons
----------------
-
-Small buttons, mainly to use inline
-
-.. code-block:: html
-
-   <p><a class="sc-button bt-create bt-small">You button</a></p>
-
-You can omit content and show a button with an icon only :
-
-.. code-block:: html
-
-   <a class="sc-button bt-create"></a>
-
-You can hide content and show it only on hover
-
-.. code-block:: html
-
-   <a class="sc-button bt-create has-hidden"><span class="show-on-hover">Showed when mouse pass on</span></a>
-
-You can customize the icon :
-
-.. code-block:: html
-
-  <a class="sc-button bt-create change-icon"><i class="fa fa-icon"></i>Button with custom icon</a>
-
-Grouping buttons
-----------------
-
-Grouping buttons can be done using ``ul.record_actions`` element (an ``ul`` list with class ``record_actions``):
-
-.. code-block:: html
-
-   <ul class="record_actions">
-
-      <li class="cancel">
-         <a class="sc-button bt-cancel">Cancel</a>
-      <li>
-
-      <li>
-         <a class="sc-button bt-save">Save</a>
-      </li>
-
-   </ul>
-
-The element with the ``cancel`` class will be set in first position.
-
-Inside table, the space between elements will be shorter.
-
-You can add the class ``record_actions_small`` if you want shorter space between elements.
-

docs/source/development/migrations.md

@@ -0,0 +1,70 @@
+###### Database Migrations
+
+Every bundle potentially brings his own database operations: to persist entities, developers have to create database schema, creating indexes,...
+
+Those schemas might be changed (the less is the better) from time to time.
+
+Consequence: each bundle should bring his own migration files, which will bring the database consistent with the operation you will run in your code. They will be gathered into the app installation, ready to be executed by the chill's installer.
+
+Currently, we use `doctrine migration`_ to manage those migration files. A `composer`_ script located in the **chill standard** component will copy the migrations from your bundle to the doctrne migration's excepted directory after each install and/or update operation.
+
+   The `doctrine migration`_ documentation
+      Learn concepts about migration files and scripts and the doctrine ORM
+
+   The `doctrine migration bundle`_ documentation
+      Learn about doctrine migration integration with a Symfony framework
+
+## Shipping migration files
+
+Migration files should be shipped under the Resource/migrations directory. You could customize the migration directory by adding extra information in your composer.json:
+
+```
+   "extra": {
+           "migration-source": "path/to/my/dir"
+       }
+```
+
+The class namespace should be `Application\Migrations`, as expected by doctrine migration. Only the files which will be executed by doctrine migration will be moved: they must have the pattern `VersionYYYYMMDDHHMMSS.php` where YYYY is the year, MM the month, DD the day, HH the hour, MM the month and SS the second of creation.
+
+They will be moved automatically by composer when you install or update a bundle.
+
+## Executing migration files
+
+The installers will have to execute migration files manually, running
+
+    `php app/console doctrine:migrations:status #will give the current status of the database`
+    `php app/console doctrine:migrations:migrate #process the update`
+
+## Updating migration files
+
+   After an installation, migration files will be executed and registered as executed in the database (the version timestamp is recorded into the :title:`migrations_versions` table). If you update your migration file code, the file will still be considered as "executed" by doctrine migration, which will not offers the possibility to run the migration again.
+
+   Consequently, updating a migration file should only be considered during the development phase and not published on public git branches. If you want to edit your database schema, you should create a new migration file, with a new timestamp, which will proceed to your schema adaptations.
+
+Every time a migration file is discovered, the composer script will check if the migration exists in the local migration directory. If yes, the script will compare two file for changes (using a md5 hash). If migrations are discovered, the script will ask the installer to know if he must replace the file or ignore it.
+
+   You can manually run a composer script by launching `composer run-script post-update-cmd` from your root chill installation's directory.
+
+## Tips for development
+
+### Migration and data
+
+Each time you create a migration script, you should ensure that it will not lead to data losing. Eventually, feel free to use intermediate steps.
+
+### Generation
+
+You can generate a migration file from the command line, using those commands:
+
+* `php app/console doctrine:migrations:diff` to generate a migration file by comparing your current database to your mapping information
+* `php app/console doctrine:migrations:generate` to generate a blank migration file.
+
+Those files will be located into `app/DoctrineMigrations` directory. You will have to copy those file to your the directory `Resources/migrations` into your bundle directory.
+
+### Comments and documentation
+
+As files are copied from your bundle to the `app/DoctrineMigrations` directory, the link between your bundle and the copied file will be unclear. Please add all relevant documentation which will allow future developers to make a link between your file and your bundle.
+
+### Inside the script
+
+The script that moves the migration files to app directory `might be found here
+<https://github.com/Champs-Libres/ComposerBundleMigration/blob/master/Composer/Migrations.php>

docs/source/development/migrations.rst

@@ -1,101 +0,0 @@
-.. Copyright (C)  2014 Champs Libres Cooperative SCRLFS
-   Permission is granted to copy, distribute and/or modify this document
-   under the terms of the GNU Free Documentation License, Version 1.3
-   or any later version published by the Free Software Foundation;
-   with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
-   A copy of the license is included in the section entitled "GNU
-   Free Documentation License".
-
-Database Migrations
-********************
-
-Every bundle potentially brings his own database operations : to persist entities, developers have to create database schema, creating indexes,... 
-
-Those schema might be changed (the less is the better) from time to time.
-
-Consequence: each bundle should bring his own migration files, which will bring the database consistent with the operation you will run in your code. They will be gathered into the app installation, ready to be executed by the chill's installer. 
-
-Currently, we use `doctrine migration`_ to manage those migration files. A `composer`_ script located in the **chill standard** component will copy the migrations from your bundle to the doctrne migration's excepted directory after each install and/or update operation.
-
-.. seealso::
-
-   The `doctrine migration`_ documentation
-      Learn concepts about migrations files and scripts and the doctrine ORM
-
-   The `doctrine migration bundle`_ documentation
-      Learn about doctrine migration integration with Symfony framework
-
-Shipping migration files
-========================
-
-Migrations files should be shipped under the Resource/migrations directory. You could customize the migration directory by adding extra information in your composer.json: 
-
-.. code-block:: json
-
-   "extra": {
-           "migration-source": "path/to/my/dir"
-       }
-
-The class namespace should be `Application\Migrations`, as expected by doctrine migration. Only the files which will be executed by doctrine migration will be moved: they must have the pattern `VersionYYYYMMDDHHMMSS.php` where YYYY is the year, MM the month, DD the day, HH the hour, MM the month and SS the second of creation.
-
-They will be moved automatically by composer when you install or update a bundle.
-
-Executing migration files
-==========================
-
-The installers will have to execute migrations files manually, running 
-
-.. code-block:: bash
-
-   php app/console doctrine:migrations:status #will give the current status of the database
-   php app/console doctrine:migrations:migrate #process the update
-
-
-Updating migration files
-=========================
-
-.. warning::
-
-   After an installation, migration files will be executed and registered as executed in the database (the version timestamp is recorded into the :title:`migrations_versions` table). If you update your migration file code, the file will still be considered as "executed" by doctrine migration, which will not offers the possibility to run the migration again.
-
-   Consequently, updating migration file should only be considered during development phase, and not published on public git branches. If you want to edit your database schema, you should create a new migration file, with a new timestamp, which will proceed to your schema adaptations.
-
-Every time a migration file is discovered, the composer'script will check if the migration exists in the local migration directory. If yes, the script will compare two file for changes (using a md5 hash). If migrations are discovered, the script will ask the installer to know if he must replace the file or ignore it.
-
-.. note::
-
-   You can manually run composer script by launching `composer run-script post-update-cmd` from your root chill installation's directory.
-
-
-.. _doctrine migration: http://www.doctrine-project.org/projects/migrations.html
-.. _doctrine migration bundle : http://symfony.com/doc/master/bundles/DoctrineMigrationsBundle/index.html
-.. _composer : https://getcomposer.org
-
-Tips for development
-====================
-
-Migration and data 
-------------------
-
-Each time you create a migration script, you should ensure that it will not lead to data losing. Eventually, feel free to use intermediate steps.
-
-Generation
-----------
-
-You can generate migration file from the command line, using those commands: 
-
-* `php app/console doctrine:migrations:diff` to generate a migration file by comparing your current database to your mapping information
-* `php app/console doctrine:migrations:generate` to generate a blank migration file.
-
-Those files will be located into `app/DoctrineMigrations` directory. You will have to copy those file to your the directory `Resources/migrations` into your bundle directory.
-
-Comments and documentation
---------------------------
-
-As files are copied from your bundle to the `app/DoctrineMigrations` directory, the link between your bundle and the copied file will be unclear. Please add all relevant documentation which will allow future developers to make a link between your file and your bundle.
-
-Inside the script
------------------
-
-The script which move the migrations files to app directory `might be found here 
-<https://github.com/Champs-Libres/ComposerBundleMigration/blob/master/Composer/Migrations.php>

docs/source/development/pagination.md

@@ -0,0 +1,153 @@
+# Pagination
+
+The Bundle `Chill\MainBundle` provides a **Pagination** api which allow you to easily divide result list on different pages.
+
+###### A simple example
+
+In the controller, get the `Chill\Main\Pagination\PaginatorFactory` from the `Container` and use this `PaginatorFactory` to create a `Paginator` instance.
+
+```php
+
+Then, render the pagination using the dedicated twig function.
+
+   {% extends "@ChillPerson/Person/layout.html.twig"  %}
+
+   {% block title 'Item list'|trans %}
+
+   {% block content %}
+
+   <table>
+
+   {# ... your items here... #}
+
+   </table>
+
+   {% if items|length < paginator.getTotalItems %}
+   {{ chill_pagination(paginator) }}
+   {% endif %}
+```
+
+The function `chill_pagination` will, by default, render a link to the 10 previous page (if they exists) and the 10 next pages (if they exists). Assuming that we are on page 5, the function will render a list to ::
+
+   Previous 1 2 3 4 **5** 6 7 8 9 10 11 12 13 14 Next
+
+## Understanding the magic
+
+### Where does the `$paginator` get the page number ?
+
+Internally, the `$paginator` object has a link to the `Request` object, and it reads the `page` parameter which contains the current page number. If this parameter is not present, the `$paginator` assumes that we are on page 1.
+
+   The `$paginator` get the current page from the request.
+
+### Where does the `$paginator` get the number of items per page ?
+
+As above, the `$paginator` can get the number of items per page from the `Request`. If none is provided, this is given by the configuration which is, by default, 50 items per page.
+
+###### `PaginatorFactory`, `Paginator` and `Page`
+
+## `PaginatorFactory`
+
+The `PaginatorFactory` may create more than one `Paginator` in a single action. Those `Paginator` instance may redirect to different routes and/or routes parameters.
+
+   // create a paginator for the route 'my_route' with some parameters (arg1 and arg2)
+    `$paginatorMyRoute = $paginatorFactory->create($total, 'my_route', array('arg1' => 'foo', 'arg2' => $bar);`
+Those parameters will override the current parameters.
+
+The `PaginatorFactory` has also some useful shortcuts :
+
+   // get current page number
+    `$paginatorFactory->getCurrentPageNumber()`
+   // get the number of items per page **for the current request**
+   `$paginatorFactory->getCurrentItemsPerPage()`
+   // get the number of the first item **for the current page**
+   `$paginatorFactory->getCurrentPageFirstItemNumber()`
+
+## Working with `Paginator` and `Page`
+
+The paginator has a function to give the number of pages that are required to display all the results and give some information about the number of items per page :
+
+   // how many page count this paginator ?
+   `$paginator->countPages(); // return 20 in our example`
+
+   // we may get the number of items per page
+   `$paginator->getItemsPerPage(); // return 20 in our example`
+
+A `Paginator` instance create instance of `Page`, each `Page`, which is responsible for generating the URL to the page number it represents. Here are some possibilities using `Page` and `Paginator` :
+
+   Get the current page
+   `$page = $paginator->getCurrentPage();`
+   On which page are we?
+   `$page->getNumber(); // return 5 in this example (we are on page 5)`
+   Generate the url for page 5
+   `$page->generateUrl(); // return '/<your route here>?page=5`
+   What is the first item number on this page ?
+   `$page->getFistItemNumber(); // return 101 in our example (20 items per page)`
+   What is the last item number on this page?
+   `$page->getLastItemNumber(); // return 120 in our example`
+
+   We can access directly the next and current page
+```
+if ($paginator->hasNextPage()) {
+       $next = $paginator->getNextPage();
+   }
+   if ($paginator->hasPreviousPage()) {
+       $previous = $paginator->getPreviousPage();
+   }
+```
+
+   We can access directly to a given page number
+```
+   $page10 = $paginator->getPage(10);``
+   if ($paginator->hasPage(10)) {
+      $page10 = $paginator->getPage(10);
+   }
+```
+
+   We can iterate over our pages through a generator
+```
+   foreach ($paginator->getPagesGenerator() as $page) {
+      $page->getNumber();
+   }
+```
+
+   Check that a page object is the current page
+
+   `$paginator->isCurrentPage($page); // return false`
+
+   When calling a page which does not exist, the [Paginator` will throw a `RuntimeException`. Example :
+
+    Our last page is 10
+
+    `$paginator->getPage(99); // out of range => throw RuntimeException`
+
+    Our current page is 1 (the first page)
+    `$paginator->getPreviousPage; // does not exists (the fist page is always 1) => throw RuntimeException`
+
+   When you create a `Paginator` for the current route and route parameters, the `Page` instances will keep the same parameters and routes :
+
+```php
+    // assuming our route is 'my_route', for the pattern '/my/{foo}/route',
+    // and the current route is '/my/value/route?arg2=bar'
+```
+
+Create a paginator for the current route and route parameters :
+      `$paginator = $paginatorFactory->create($total);`
+
+Get the next page
+```
+if ($paginator->hasNext()) {
+         $next = $paginator->getNextPage();
+
+         // get the route to the page
+         $page->generateUrl(); // will print 'my/value/route?arg2=bar&page=2'
+      }
+```
+Having a look at the `full classes' documentation may provide some [ useful information ](http://api.chill.social/Chill-Main/master/namespace-Chill.MainBundle.Pagination.html).
+
+###### Customizing the rendering of twig's [chill_pagination`
+
+You can provide your own layout for rendering the pagination: provides your twig template as a second argument :
+
+   {{ chill_pagination(paginator, 'MyBundle:Pagination:MyTemplate.html.twig') }}
+
+The template will receive the `$paginator` as `paginator` variable. Let's have a look `at the [ current template ](https://framagit.org/Chill-project/Chill-Main/blob/master/Resources/views/Pagination/long.html.twig).

docs/source/development/pagination.rst

@@ -1,191 +0,0 @@
-.. Copyright (C)  2016 Champs Libres Cooperative SCRLFS
-   Permission is granted to copy, distribute and/or modify this document
-   under the terms of the GNU Free Documentation License, Version 1.3
-   or any later version published by the Free Software Foundation;
-   with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
-   A copy of the license is included in the section entitled "GNU
-   Free Documentation License".
-
-
-.. _pagination-ref:
-
-Pagination
-##########
-
-The Bundle :code:`Chill\MainBundle` provides a **Pagination** api which allow you to easily divide results list on different pages.
-
-A simple example
-****************
-
-In the controller, get the :code:`Chill\Main\Pagination\PaginatorFactory` from the `Container` and use this :code:`PaginatorFactory` to create a :code:`Paginator` instance.
-
-
-.. literalinclude:: pagination/example.php
-   :language: php
-
-
-Then, render the pagination using the dedicated twig function.
-
-.. code-block:: html+twig
-
-   {% extends "@ChillPerson/Person/layout.html.twig"  %}
-
-   {% block title 'Item list'|trans %}
-
-   {% block content %}
-
-   <table>
-
-   {# ... your items here... #}
-
-   </table>
-
-   {% if items|length < paginator.getTotalItems %}
-   {{ chill_pagination(paginator) }}
-   {% endif %}
-
-
-The function :code:`chill_pagination` will, by default, render a link to the 10 previous page (if they exists) and the 10 next pages (if they exists). Assuming that we are on page 5, the function will render a list to ::
-
-   Previous 1 2 3 4 **5** 6 7 8 9 10 11 12 13 14 Next
-
-Understanding the magic
-=======================
-
-Where does the :code:`$paginator` get the page number ?
--------------------------------------------------------
-
-Internally, the :code:`$paginator` object has a link to the :code:`Request` object, and it reads the :code:`page` parameter which contains the current page number. If this parameter is not present, the :code:`$paginator` assumes that we are on page 1.
-
-.. figure:: /_static/puml/pagination-sequence.png
-
-   The :code:`$paginator` get the current page from the request.
-
-Where does the :code:`$paginator` get the number of items per page ?
---------------------------------------------------------------------
-
-As above, the :code:`$paginator` can get the number of items per page from the :code:`Request`. If none is provided, this is given by the configuration which is, by default, 50 items per page.
-
-:code:`PaginatorFactory`, :code:`Paginator` and :code:`Page`
-************************************************************
-
-:code:`PaginatorFactory`
-========================
-
-The :code:`PaginatorFactory` may create more than one :code:`Paginator` in a single action. Those :code:`Paginator` instance may redirect to different routes and/or routes parameters.
-
-.. code-block:: php
-
-   // create a paginator for the route 'my_route' with some parameters (arg1 and arg2)
-   $paginatorMyRoute = $paginatorFactory->create($total, 'my_route', array('arg1' => 'foo', 'arg2' => $bar);
-
-Those parameters will override the current parameters.
-
-The :code:`PaginatorFactory` has also some useful shortcuts : 
-
-.. code-block:: php
-
-   // get current page number
-   $paginatorFactory->getCurrentPageNumber( )
-   // get the number of items per page **for the current request**
-   $paginatorFactory->getCurrentItemsPerPage( )
-   // get the number of the first item **for the current page**
-   $paginatorFactory->getCurrentPageFirstItemNumber( )
-
-
-Working with :code:`Paginator` and :code:`Page`
-===============================================
-
-The paginator has some function to give the number of pages are required to displayed all the results, and give some information about the number of items per page :
-
-.. code-block:: php
-
-   // how many page count this paginator ?
-   $paginator->countPages(); // return 20 in our example
-
-   // we may get the number of items per page
-   $paginator->getItemsPerPage(); // return 20 in our example
-
-A :code:`Paginator` instance create instance of :code:`Page`, each :code:`Page`, which is responsible for generating the URL to the page number it represents. Here are some possibilities using :code:`Page` and :code:`Paginator` :
-
-.. code-block:: php
-
-   // get the current page
-   $page = $paginator->getCurrentPage();
-   // on which page are we ?
-   $page->getNumber(); // return 5 in this example (we are on page 5)
-   // generate the url for page 5
-   $page->generateUrl(); // return '/<your route here>?page=5
-   // what is the first item number on this page ?
-   $page->getFistItemNumber(); // return 101 in our example (20 items per page)
-   // what is the last item number on this page ?
-   $page->getLastItemNumber(); // return 120 in our example
-
-   // we can access directly the next and current page
-   if ($paginator->hasNextPage()) {
-       $next = $paginator->getNextPage();
-   }
-   if ($paginator->hasPreviousPage()) {
-       $previous = $paginator->getPreviousPage();
-   }
-
-   // we can access directly to a given page number
-   if ($paginator->hasPage(10)) {
-      $page10 = $paginator->getPage(10);
-   }
-
-   // we can iterate over our pages through a generator
-   foreach ($paginator->getPagesGenerator() as $page) {
-      $page->getNumber();
-   }
-
-   // check that a page object is the current page
-   $paginator->isCurrentPage($page); // return false
-
-.. warning:: 
-
-   When calling a page which does not exists, the :code:`Paginator` will throw a `RuntimeException`. Example :
-
-   .. code-block:: php
-
-      // our last page is 10
-      $paginator->getPage(99); // out of range => throw `RuntimeException`
-
-      // our current page is 1 (the first page)
-      $paginator->getPreviousPage; // does not exists (the fist page is always 1) => throw `RuntimeException`
-
-.. note::
-
-   When you create a :code:`Paginator` for the current route and route parameters, the :code:`Page` instances will keep the same parameters and routes :
-
-   .. code-block:: php
-
-      // assuming our route is 'my_route', for the pattern '/my/{foo}/route', 
-      // and the current route is '/my/value/route?arg2=bar'
-
-      // create a paginator for the current route and route parameters :
-      $paginator = $paginatorFactory->create($total);
-
-      // get the next page
-      if ($paginator->hasNext()) {
-         $next = $paginator->getNextPage();
-
-         // get the route to the page
-         $page->generateUrl(); // will print 'my/value/route?arg2=bar&page=2'
-      }
-
-
-Having a look to the `full classes documentation may provide some useful information <http://api.chill.social/Chill-Main/master/namespace-Chill.MainBundle.Pagination.html>`_.
-
-
-Customizing the rendering of twig's :code:`chill_pagination`
-************************************************************
-
-You can provide your own layout for rendering the pagination: provides your twig template as a second argument :
-
-.. code-block:: html+jinja
-
-   {{ chill_pagination(paginator, 'MyBundle:Pagination:MyTemplate.html.twig') }}
-
-The template will receive the :code:`$paginator` as :code:`paginator` variable. Let's have a look `at the current template <https://framagit.org/Chill-project/Chill-Main/blob/master/Resources/views/Pagination/long.html.twig>`_.
-

docs/source/development/render-entity.md

@@ -1,36 +1,28 @@
-
-Rendering entity automatically
-##############################
+# Rendering entity automatically
 
 Some entity need to be rendered automatically for a couple of times: a person, a user, ...
 
 One can use some twig filter to render those entities:
 
-.. code-block:: twig
-
    {{ person|chill_entity_render_box }}
 
-Define a renderer
-=================
+## Define a renderer
 
-By default, the object passed through the renderer will be rendered using the :code:`__toString()` method. To customize this behaviour, you have to define a service and tag it using :code:`chill.render_entity`.
+By default, the object passed through the renderer will be rendered using the `__toString()` method. To customize this behaviour, you have to define a service and tag it using `chill.render_entity`.
 
 The rendered is implemented using :class:`Chill\MainBundle\Templating\Entity\ChillEntityRenderInterface`. This interface has 3 methods:
 
-* :code:`public function supports($entity, array $options): bool`: return true if the :code:`$entity` given in parameter, with custom options, is supported by this renderer;
-* :code:`public function renderString($entity, array $options): string`: render the entity as a single string, for instance in a select list;
-* :code:`public function renderBox($entity, array $options): string`: render the entity in an html box.
+* `public function supports($entity, array $options): bool`: return true if the `$entity` given in parameter, with custom options, is supported by this renderer;
+* `public function renderString($entity, array $options): string`: render the entity as a single string, for instance in a select list;
+* `public function renderBox($entity, array $options): string`: render the entity in a HTML box.
 
-.. warning::
+   The HTML returned by `renderBox` **MUST BE SAFE** of any XSS injection.
 
-   The HTML returned by :code:`renderBox` **MUST BE SAFE** of any XSS injection.
-
-:class:`Chill\MainBundle\Templating\Entity\AbstractChillEntityRender` provides some useful methods to get the opening and closing boxes that should be used.
+`Chill\MainBundle\Templating\Entity\AbstractChillEntityRender` provides some useful methods to get the opening and closing boxes that should be used.
 
 Usage about rendering comment:
 
-.. code-block:: php
-
+```php
    namespace Chill\MainBundle\Templating\Entity;
 
    use Chill\MainBundle\Entity\Embeddable\CommentEmbeddable;
@@ -108,47 +100,41 @@ Usage about rendering comment:
            return $entity instanceof CommentEmbeddable;
        }
    }
+```
 
 Logic inside the template:
 
-.. code-block:: twig
-
+```twig
+   {# @var opening_box: string #}
+   {# @var closing_box: string #}
    {{ opening_box|raw }}
    <div>
       {# logic for rendering #}
-   </div> 
+   </div>
    {{ closing_box|raw }}
+```
 
-Usage in templates
-==================
+## Usage in templates
 
-For rendering entity as a box:
+For rendering an entity as a box:
 
-.. code-block:: twig
+   `{{ entity|chill_entity_render_box }}`
 
-   {{ entity|chill_entity_render_box }}
+For rendering an entity as a string:
 
-For rendering entity as a string:
+   `{{ entity|chill_entity_render_string }}`
 
-.. code-block:: twig
+## Available renderer and options
 
-   {{ entity|chill_entity_render_string }}
-
-Available renderer and options
-==============================
-
-:code:`Person` (Person Bundle)
-------------------------------
+### `Person` (Person Bundle)
 
 * no options
 
-:code:`CommentEmbeddable` (Main Bundle)
----------------------------------------
+### `CommentEmbeddable` (Main Bundle)
 
-Options:
-
-* :code:`user`: options which will be passed to "user" renderer
-* :code:`disable_markdown`: disable markdown renderer, default to :code:`FALSE`
-* :code:`limit_lines` (integer) limit the number of lines. Default to :code:`NULL`. May be an integer.
-* :code:`metadata` (boolean): show the last updating user and last updating date. Default to :code:`TRUE`.
+Options :
 
+* `user`: options, which will be passed to "user" renderer
+* `disable_markdown`: disable markdown renderer, default to `FALSE`
+* `limit_lines` (integer) limit the number of lines. Default to `NULL`. Can be an integer.
+* `metadata` (boolean): show the last updating user and last updating date. Default to `TRUE`.

docs/source/development/routing.md

@@ -1,40 +1,24 @@
-.. Copyright (C)  2014 Champs Libres Cooperative SCRLFS
-   Permission is granted to copy, distribute and/or modify this document
-   under the terms of the GNU Free Documentation License, Version 1.3
-   or any later version published by the Free Software Foundation;
-   with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
-   A copy of the license is included in the section entitled "GNU
-   Free Documentation License".
+# Routing
 
+Our goal is to ease the installation of the different bundles. Users should not have to dive into complicated config files to install bundles.
 
-Routing
-#######
+## A routing loader is available for all bundles
 
-Our goal is to ease the installation of the different bundle. Users should not have to dive into complicated config files to install bundles.
-
-A routing loader available for all bundles
-===========================================
-
-A Chill bundle may rely on the Routing Loader defined in ChillMain. 
+A Chill bundle may rely on the Routing Loader defined in ChillMain.
 
 The loader will load `yml` or `xml` files. You simply have to add them into `chill_main` config
 
-.. code-block:: yaml
-
    chill_main:
    # ... other stuff here
       routing:
          resources:
             - @ChillMyBundle/Resources/config/routing.yml
 
-Load routes automatically
--------------------------
+### Load routes automatically
 
-But this force users to modify config files. To avoid this, you may prepend config implementing the `PrependExtensionInterface` in the `YourBundleExtension` class. This is an example from **chill main** bundle : 
-
-
-.. code-block:: php
+But this forces users to modify config files. To avoid this, you may prepend config implementing the `PrependExtensionInterface` in the `YourBundleExtension` class. This is an example from **chill main** bundle :
 
+```php
    namespace Chill\MainBundle\DependencyInjection;
 
    use Symfony\Component\DependencyInjection\ContainerBuilder;
@@ -49,7 +33,7 @@ But this force users to modify config files. To avoid this, you may prepend conf
            // ...
        }
 
-       public function prepend(ContainerBuilder $container) 
+       public function prepend(ContainerBuilder $container)
        {
 
            //add current route to chill main
@@ -64,5 +48,4 @@ But this force users to modify config files. To avoid this, you may prepend conf
            ));
        }
    }
-
-
+```

docs/source/development/run-tests.md

@@ -0,0 +1,54 @@
+Permission is granted to copy, distribute and/or modify this document
+   under the terms of the GNU Free Documentation License, Version 1.3
+   or any later version published by the Free Software Foundation;
+   with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+   A copy of the license is included in the section entitled "GNU
+   Free Documentation License".
+
+###### Run tests
+
+In reason of the Chill architecture, test should be runnable from the bundle's directory and works correctly: this will allow continuous integration tools to run tests automatically.
+
+## From chill app
+
+This is the most convenient method for developer: run test for chill bundle from the main app.
+
+   # run into a container
+   `docker-compose exec --user $(id -u) php bash`
+   # execute all tests suites
+   `bin/phpunit`
+   # ... or execute a single test
+   `bin/phpunit vendor/chill-project/chill-bundles/src/Bundle/ChillMainBundle/Tests/path/to/FileTest.php`
+
+You can also run tests in a single command:
+
+   `docker-compose exec --user $(id -u) php bin/phpunit`
+
+### Tests from a bundle (chill-bundles)
+
+Those tests need the whole symfony app to execute Application Tests (which test html page).
+
+For ease, the app is cloned using a `git submodule`, which clone the main app into `tests/app`, and tests are bootstrapped to this app. The dependencies are also installed into `tests/app/vendor` to ensure compliance with relative path from this symfony application.
+
+You may boostrap the tests for the chill bundle this way:
+
+   # ensure to be located into the environment (provided by docker suits well)
+   `docker-compose exec --user $(id -u) php bash`
+   # go to chill subdirectory
+   `cd vendor/chill-project/chill-bundles`
+   # install submodule
+   `git submodule init`
+   `git submodule update`
+   # install composer and dependencies
+   `curl -sS https://getcomposer.org/installer | php`
+   # run tests
+   `bin/phpunit`
+
+   If you are on a fresh installation, you will need to migrate database schema.
+
+   The path to the console tool must be adapted to the app. To load migration and add fixtures, one can execute the following commands:
+
+   ```bash
+   tests/app/bin/console doctrine:migrations:migrate
+   tests/app/bin/console doctrine:fixtures:load
+   ```

docs/source/development/run-tests.rst

@@ -1,68 +0,0 @@
-.. Copyright (C)  2014 Champs Libres Cooperative SCRLFS
-   Permission is granted to copy, distribute and/or modify this document
-   under the terms of the GNU Free Documentation License, Version 1.3
-   or any later version published by the Free Software Foundation;
-   with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
-   A copy of the license is included in the section entitled "GNU
-   Free Documentation License".
-
-Run tests
-*********
-
-In reason of the Chill architecture, test should be runnable from the bundle's directory and works correctly: this will allow continuous integration tools to run tests automatically. 
-
-From chill app
-==============
-
-This is the most convenient method for developer: run test for chill bundle from the main app.
-
-.. code-block:: bash
-
-   # run into a container
-   docker-compose exec --user $(id -u) php bash
-   # execute all tests suites
-   bin/phpunit
-   # .. or execute a single test
-   bin/phpunit vendor/chill-project/chill-bundles/src/Bundle/ChillMainBundle/Tests/path/to/FileTest.php
-
-You can also run tests in a single command:
-
-.. code-block:: bash
-
-   docker-compose exec --user $(id -u) php bin/phpunit
-
-
-Tests from a bundle (chill-bundles)
------------------------------------
-
-Those tests needs the whole symfony app to execute Application Tests (which test html page).
-
-For ease, the app is cloned using a :code:`git submodule`, which clone the main app into :code:`tests/app`, and tests are bootstrapped to this app. The dependencies are also installed into `tests/app/vendor` to ensure compliance with relative path from this symfony application.
-
-You may boostrap the tests fro the chill bundle this way:
-
-.. code-block:: bash
-
-   # ensure to be located into the environement (provided by docker suits well)
-   docker-compose exec --user $(id -u) php bash
-   # go to chill subdirectory
-   cd vendor/chill-project/chill-bundles
-   # install submodule
-   git submodule init
-   git submodule update
-   # install composer and dependencies
-   curl -sS https://getcomposer.org/installer | php
-   # run tests
-   bin/phpunit
-
-.. note::
-
-   If you are on a fresh install, you will need to migrate database schema. 
-
-   The path to console tool must be adapted to the app. To load migration and add fixtures, one can execute the following commands:
-
-   .. code-block:: bash
-      
-      tests/app/bin/console doctrine:migrations:migrate
-      tests/app/bin/console doctrine:fixtures:load
-

docs/source/development/searching.md

@@ -0,0 +1,222 @@
+###### Searching
+
+Chill should provide information needed by users when they need it. Searching within bundle, entities, ... is an important feature to achieve this goal.
+
+The Main Bundle provides interfaces to ease the developer's work. It will also attempt that search will work in the same way accross bundles.
+
+   :local:
+
+   [Our blog post about searching (in French) ](http://blog.champs-libres.coop/vie-des-champs/2015/01/06/va-chercher-chill-la-recherche-dans-chill-logiciel-libre-service-social.html)
+      This blog post gives some information for end-users about searching.
+
+   [The issue about search behaviour ](https://redmine.champs-libres.coop/issues/377)
+      Where the search behavior is defined.
+
+## Searching at a glance for developers
+
+Chill suggests using an easy-to-learn language search.
+
+   We are planning to provide a form to create an automatic search pattern according to this language. Watch the [issue regarding this feature ](https://redmine.champs-libres.coop/issues/389).
+
+The language is an association of search terms. Search terms may contain :
+
+- **a domain**: this is "the domain you want to search": it may some entities like people, reports, ... Example: [@person` to search accross people, `@report` to browse reports, ... The search pattern may have **a maximum of one** domain by search, providing more should throw an error, and trigger a warning for users.
+- **arguments and their values** : This is "what you search." Arguments narrow the search to specific fields: username, date of birth, nationality, ... The syntax is `argument:value`. I.e.: ` birthdate:2014-12-15`, `firstname:Depardieu`, ... **Arguments are optional**. If the value of an argument contains spaces or characters like punctuation, quotes ("), the value should be provided between parenthesis : `firstname:(Van de snoeck)`, `firstname:(M'bola)`, ...
+- **default value** : this the "rest" of the search, not linked with any arguments or domain. Example : `@person dep` (`dep` is the "default value"), or simply `dep` if any domain is provided (which is perfectly acceptable). If a string is not idenfied as argument or domain, it will be present in the "default" term.
+
+If a search pattern (provided by the user) does not contain any domain, the search must be run across default domain/search modules.
+
+A domain may be supported by different search modules. For instance, if you provide the domain `@person`, the end-user may receive results of exact firstname/lastname, but also result with spelling suggestion, ... **But** if results do not fit into the first page (if you have 75 results and the screen show only 50 results), the next page should contains only the results from the required module.
+
+For instance: a user searches across people by firstname/lastname, the exact spelling contains 10 results, the "spelling suggestion" results contain 75 names, but show only the first 50. If the user want to see the last 25, the next screen should not contains the results by firstname/lastname.
+
+## Allowed characters as arguments
+
+To execute regular expression, the allowed characters in arguments are a-z characters, numbers, and the sign '-'. Spaces and special characters like accents are note allowed (the accents are removed during parsing).
+
+## Special characters and uppercase
+
+The search should not care about lowercase/uppercase and accented characters. Currently, they are removed automatically by the `chill.main.search_provider`.
+
+## Implementing a search module for dev
+
+To implement a search module, you should :
+
+- create a class which implements the `Chill\MainBundle\Search\SearchInterface` class. An abstract class `Chill\MainBundle\Search\AbstractSearch` will provide useful assertions for parsing date string to `DateTime` objects, ...
+- register the class as a service, and tag the service with `chill.search` and an appropriate alias
+
+The search logic is provided under the  `/search` route.
+
+   `The implementation of a search module in the Person bundle ](https://github.com/Chill-project/Person/blob/master/Search/PersonSearch.php)
+      An example of implementation https://github.com/Chill-project/Main/blob/master/DependencyInjection/SearchableServicesCompilerPass.php
+
+   **Internals explained** : the services tagged with [chill.search` are gathered into the `chill.main.search_provider` service during compilation (`see the compiler pass ](https://github.com/Chill-project/Main/blob/master/DependencyInjection/SearchableServicesCompilerPass.php)).
+
+   The [chill.main.search_provider` service allows to :
+
+   - retrieve all results (as HTML string) for all search modules concerned by the search (according to the domain provided or modules marked as default)
+   - retrieve result for one search module
+
+### The SearchInterface class
+
+```php
+   namespace Chill\PersonBundle\Search;
+
+   use Chill\MainBundle\Search\AbstractSearch;
+   use Doctrine\ORM\EntityManagerInterface;
+   use Chill\PersonBundle\Entity\Person;
+   use Symfony\Component\DependencyInjection\ContainerInterface;
+   use Symfony\Component\DependencyInjection\ContainerAware;
+   use Symfony\Component\DependencyInjection\ContainerAwareTrait;
+   use Chill\MainBundle\Search\ParsingException;
+
+   class PersonSearch extends AbstractSearch
+   {
+
+       // indicate which domain you support
+       // you may respond TRUE to multiple domain, according to your logic
+       public function supports($domain, $format='html')
+       {
+           return 'person' === $domain;
+       }
+
+       // if your domain must be called when no domain is provided, should return true
+       public function isActiveByDefault()
+       {
+           return true;
+       }
+
+       // if multiple modules respond to the same domain, indicate an order for your search.
+       public function getOrder()
+       {
+           return 100;
+       }
+
+       // This is where your search logic should be executed.
+       // This method must return an HTML string (a string with HTML tags)
+       // see below about the structure of the $term array
+       public function renderResult(array $terms, $start = 0, $limit = 50, array $options = array(), $format = 'html')
+       {
+           return $this->container->get('templating')->render('ChillPersonBundle:Person:list.html.twig',
+                   array(
+                       // you should implement the `search` function somewhere :-)
+                       'persons' => $this->search($terms, $start, $limit, $options),
+                       // recomposePattern is available in AbstractSearch class
+                       'pattern' => $this->recomposePattern($terms, array('nationality',
+                           'firstname', 'lastname', 'birthdate', 'gender'), $terms['_domain']),
+                       // you should implement the `count` function somewhere :-)
+                       'total' => $this->count($terms)
+                   ));
+       }
+   }
+```
+
+##### Values for `$options`
+
+`$options` is an array with the following keys:
+
+- `SearchInterface::SEARCH_PREVIEW_OPTION` (bool): if the current view is a preview (the first 5 results) or not ;
+- `SearchInterface::REQUEST_QUERY_PARAMETERS` (bool): some parameters added to the query (under the key `SearchInterface::REQUEST_QUERY_KEY_ADD_PARAMETERS`) and that can be interpreted. Used, for instance, when calling a result in json format when searching for interactive picker form.
+
+##### Structure of array `$term`
+
+The array term is parsed automatically by the `main.chill.search_provider` service.
+
+   If you need to parse a search pattern, you may use the function `parse($pattern)` provided by the service.
+
+The array `$term` have the following structure after parsing :
+
+```php
+   array(
+      '_domain' => 'person', //the domain, without the '@'
+      'argument1' => 'value', //the argument1, with his value
+      'argument2' => 'my value with spaces', //the argument2
+      '_default' => 'abcde ef' // the default term
+   );
+```
+
+The original search would have been : `@person argument1:value argument2:(my value with spaces) abcde ef`
+
+   The search values are always unaccented.
+
+##### Returning a result in JSON
+
+The JSON format is mainly used by "select2" widgets.
+
+When returning a result in JSON, the SearchInterface should only return an array with following keys:
+
+- `more` (bool): if the search has more result than the current page ;
+- `results` (array): a list of a result, where:
+
+    - `text` (string): the text that should be displayed in browser ;
+    - `id` (string): the id of the entity.
+
+### Register the service
+
+You should add your service in the configuration, and add a `chill.search` tag and an alias.
+
+Example :
+
+```yaml
+   services:
+      chill.person.search_person:
+         class: Chill\PersonBundle\Search\PersonSearch
+         #your logic here
+         tags:
+            - { name: chill.search, alias: 'person_regular' }
+```
+
+The alias will be used to get the results narrowed to this search module, in case of pagination (see above).
+
+## Parsing date
+
+The class `Chill\MainBundle\Search\AbstractSearch` provides a method to parse date :
+
+   //from subclasses
+   `$date = $this->parseDate($string);`
+
+`$date` will be an instance of `DateTime ](http://php.net/manual/en/class.datetime.php).
+
+   [The possibility to add periods instead of date ](https://redmine.champs-libres.coop/issues/390)
+       Which may be a future improvement for search with date.
+
+## Exceptions
+
+The logic of the search is handled by the controller for the `/search` path.
+
+You should throw those Exceptions from your instance of `SearchInterface` if needed :
+
+Chill\MainBundle\Search\ParsingException
+   If the terms do not fit your search logic (for instance, conflicting terms)
+
+## Expected behaviour
+
+### Operators between multiple terms
+
+Multiple terms should be considered are "AND" instructions :
+
+@person nationality:RU firstname:dep
+   the people having the Russian nationality AND having DEP in their name
+
+@person birthdate:2015-12-12 charles
+   the people having 'charles' in their name or firstname AND born on December 12, 2015
+
+### Spaces in default
+
+Spaces in default terms should be considered as "AND" instruction
+
+@person charle dep
+   people have "dep" AND "charles" in their firstname or lastname. Match "Charles Depardieu" but not "Gérard Depardieu" ('charle' is not present)
+
+### Rendering
+
+The rendering should contain :
+
+- the total number of results ;
+- the search pattern in the search language. The aim of this is to let users learn the search language easily.
+- a title
+
+## Frequently Asked Questions (FAQ)
+
+Why does renderResults return an HTML string and not a structured array?
+   It seems that the form of results may vary (according to access-right logic, ...) and is not easily structurable

docs/source/development/searching.rst

@@ -1,276 +0,0 @@
-.. Copyright (C)  2014 Champs Libres Cooperative SCRLFS
-   Permission is granted to copy, distribute and/or modify this document
-   under the terms of the GNU Free Documentation License, Version 1.3
-   or any later version published by the Free Software Foundation;
-   with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
-   A copy of the license is included in the section entitled "GNU
-   Free Documentation License".
-
-
-Searching
-*********
-
-Chill should provide information needed by users when they need it. Searching within bundle, entities,... is an important feature to achieve this goal.
-
-The Main Bundle provide interfaces to ease the developer work. It will also attempt that search will work in the same way accross bundles.
-
-.. contents:: Table of content
-   :local:
-
-.. seealso::
-
-   `Our blog post about searching (in French) <http://blog.champs-libres.coop/vie-des-champs/2015/01/06/va-chercher-chill-la-recherche-dans-chill-logiciel-libre-service-social.html>`_
-      This blog post give some information for end-users about searching.
-
-   `The issue about search behaviour <https://redmine.champs-libres.coop/issues/377>`_
-      Where the search behaviour is defined.
-
-Searching in a glance for developers
-====================================
-
-Chill suggests to use an easy-to-learn language search.
-
-.. note::
-
-   We are planning to provide a form to create automatically search pattern according to this language. Watch the `issue regarding this feature <https://redmine.champs-libres.coop/issues/389>`_.
-
-The language is an association of search terms. Search terms may contains : 
-
-- **a domain**: this is "the domain you want to search" : it may some entities like people, reports, ... Example : `@person` to search accross people, `@report` to browse reports, ... The search pattern may have **a maximum of one** domain by search, providing more should throw an error, and trigger a warning for users.
-- **arguments and their values** : This is "what you search". Arguments narrow the search to specific fields : username, date of birth, nationality, ... The syntax is `argument:value`. I.e.: ` birthdate:2014-12-15`, `firstname:Depardieu`, ... **Arguments are optional**. If the value of an argument contains spaces or characters like punctuation, quotes ("), the value should be provided between parenthesis : `firstname:(Van de snoeck)`, `firstname:(M'bola)`, ...
-- **default value** : this the "rest" of the search, not linked with any arguments or domain. Example : `@person dep` (`dep` is the "default value"), or simply `dep` if any domain is provided (which is perfectly acceptable). If a string is not idenfied as argument or domain, it will be present in the "default" term.
-
-If a search pattern (provided by the user) does not contains any domain, the search must be run across default domain/search modules.
-
-A domain may be supported by different search modules. For instance, if you provide the domain `@person`, the end-user may receive results of exact firstname/lastname, but also result with spelling suggestion, ... **But** if results do not fit into the first page (if you have 75 results and the screen show only 50 results), the next page should contains only the results from the required module. 
-
-For instance : a user search across people by firstname/lastname, the exact spelling contains 10 results, the "spelling suggestion" results contains 75 names, but show only the first 50. If the user want to see the last 25, the next screen should not contains the results by firstname/lastname.
-
-Allowed characters as arguments
-===============================
-
-In order to execute regular expression, the allowed chararcters in arguments are a-z characters, numbers, and the sign '-'. Spaces and special characters like accents are note allowed (the accents are removed during parsing).
-
-Special characters and uppercase
-================================
-
-The search should not care about lowercase/uppercase and accentued characters. Currently, they are removed automatically by the `chill.main.search_provider`.
-
-Implementing search module for dev
-===================================
-
-To implement a search module, you should : 
-
-- create a class which implements the `Chill\MainBundle\Search\SearchInterface` class. An abstract class `Chill\MainBundle\Search\AbstractSearch` will provide useful assertions for parsing date string to `DateTime` objects, ...
-- register the class as a service, and tag the service with `chill.search` and an appropriate alias
-
-The search logic is provided under the  `/search` route.
-
-.. seealso::
-
-   `The implementation of a search module in Person bundle <https://github.com/Chill-project/Person/blob/master/Search/PersonSearch.php>`_
-      An example of implementationhttps://github.com/Chill-project/Main/blob/master/DependencyInjection/SearchableServicesCompilerPass.php
-
-.. note::
-
-   **Internals explained** : the services tagged with `chill.search` are gathered into the `chill.main.search_provider` service during compilation (`see the compiler pass <https://github.com/Chill-project/Main/blob/master/DependencyInjection/SearchableServicesCompilerPass.php>`_). 
-
-   The `chill.main.search_provider` service allow to : 
-  
-   - retrieve all results (as html string) for all search module concerned by the search (according to the domain provided or modules marked as default)
-   - retrieve result for one search module
-
-The SearchInterface class
--------------------------
-
-.. code-block:: php
-
-   namespace Chill\PersonBundle\Search;
-
-   use Chill\MainBundle\Search\AbstractSearch;
-   use Doctrine\ORM\EntityManagerInterface;
-   use Chill\PersonBundle\Entity\Person;
-   use Symfony\Component\DependencyInjection\ContainerInterface;
-   use Symfony\Component\DependencyInjection\ContainerAware;
-   use Symfony\Component\DependencyInjection\ContainerAwareTrait;
-   use Chill\MainBundle\Search\ParsingException;
-
-   class PersonSearch extends AbstractSearch
-   {
-
-       // indicate which domain you support
-       // you may respond TRUE to multiple domain, according to your logic
-       public function supports($domain, $format='html')
-       {
-           return 'person' === $domain;
-       }
-
-       // if your domain must be called when no domain is provided, should return true
-       public function isActiveByDefault()
-       {
-           return true;
-       }
-       
-       // if multiple module respond to the same domain, indicate an order for your search.
-       public function getOrder()
-       {
-           return 100;
-       }
-
-
-       // This is where your search logic should be executed. 
-       // This method must return an HTML string (a string with HTML tags)
-       // see below about the structure of the $term array
-       public function renderResult(array $terms, $start = 0, $limit = 50, array $options = array(), $format = 'html')
-       {  
-           return $this->container->get('templating')->render('ChillPersonBundle:Person:list.html.twig', 
-                   array( 
-                       // you should implements the `search` function somewhere :-)
-                       'persons' => $this->search($terms, $start, $limit, $options),
-                       // recomposePattern is available in AbstractSearch class
-                       'pattern' => $this->recomposePattern($terms, array('nationality',
-                           'firstname', 'lastname', 'birthdate', 'gender'), $terms['_domain']),
-                       // you should implement the `count` function somewhere :-)
-                       'total' => $this->count($terms)
-                   ));
-       }
-   }
-
-
-Values for :code:`$options`
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-:code:`$options` is an array with the following keys: 
-
-- :code:`SearchInterface::SEARCH_PREVIEW_OPTION` (bool): if the current view is a preview (the first 5 results) or not ;
-- :code:`SearchInterface::REQUEST_QUERY_PARAMETERS` (bool): some parameters added to the query (under the key :code:`SearchInterface::REQUEST_QUERY_KEY_ADD_PARAMETERS`) and that can be interpreted. Used, for instance, when calling a result in json format when searching for interactive picker form.
-
-
-
-
-Structure of array `$term`
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The array term is parsed automatically by the `main.chill.search_provider` service. 
-
-.. note::
-   If you need to parse a search pattern, you may use the function `parse($pattern)` provided by the service.
-
-The array `$term` have the following structure after parsing :
-
-.. code-block:: php
-
-   array(
-      '_domain' => 'person', //the domain, without the '@'
-      'argument1' => 'value', //the argument1, with his value
-      'argument2' => 'my value with spaces', //the argument2
-      '_default' => 'abcde ef' // the default term
-   );
-
-The original search would have been : `@person argument1:value argument2:(my value with spaces) abcde ef`
-
-.. warning::
-   The search values are always unaccented.
-
-Returning a result in json
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The json format is mainly used by "select2" widgets.
-
-When returning a result in json, the SearchInterface should only return an array with following keys:
-
-- :code:`more` (bool): if the search has more result than the current page ;
-- :code:`results` (array): a list of result, where: 
-
-    - :code:`text` (string): the text that should be displayed in browser ;
-    - :code:`id` (string): the id of the entity.
-
-
-
-Register the service
---------------------
-
-You should add your service in the configuration, and add a `chill.search` tag and an alias.
-
-Example : 
-
-.. code-block:: yaml
-
-   services:
-      chill.person.search_person:
-         class: Chill\PersonBundle\Search\PersonSearch
-         #your logic here
-         tags:
-            - { name: chill.search, alias: 'person_regular' }
-
-The alias will be used to get the results narrowed to this search module, in case of pagination (see above).
-
-Parsing date
-============
-
-The class `Chill\MainBundle\Search\AbstractSearch` provides a method to parse date :
-
-.. code-block:: php
-
-   //from subclasses
-   $date = $this->parseDate($string);
-
-`$date` will be an instance of `DateTime <http://php.net/manual/en/class.datetime.php>`_.
-
-.. seealso::
-
-   `The possibility to add periods instead of date <https://redmine.champs-libres.coop/issues/390>`_
-       Which may be a future improvement for search with date.
-
-Exceptions
-==========
-
-The logic of the search is handled by the controller for the `/search` path. 
-
-You should throw those Exception from your instance of `SearchInterface` if needed : 
-
-Chill\MainBundle\Search\ParsingException
-   If the terms does not fit your search logic (for instance, conflicting terms)
-
-Expected behaviour
-==================
-
-Operators between multiple terms
---------------------------------
-
-Multiple terms should be considered are "AND" instructions :
-
-@person nationality:RU firstname:dep 
-   the people having the Russian nationality AND having DEP in their name
-
-@person birthdate:2015-12-12 charles 
-   the people having 'charles' in their name or firstname AND born on December 12 2015
-
-Spaces in default
------------------
-
-Spaces in default terms should be considered as "AND" instruction
-
-@person charle dep 
-   people having "dep" AND "charles" in their firstname or lastname. Match "Charles Depardieu" but not "Gérard Depardieu" ('charle' is not present)
-
-Rendering
----------
-
-The rendering should contains :
-
-- the total number of results ;
-- the search pattern in the search language. The aim of this is to let users learn the search language easily.
-- a title
-
-Frequently Asked Questions (FAQ)
-================================
-
-Why renderResults returns an HTML string and not structured array ?
-   It seems that the form of results may vary (according to access-right logic, ...) and is not easily structurable
-
-
-
-
-
-

docs/source/development/timelines.md

@@ -1,49 +1,31 @@
-.. Copyright (C)  2015 Champs Libres Cooperative SCRLFS
-   Permission is granted to copy, distribute and/or modify this document
-   under the terms of the GNU Free Documentation License, Version 1.3
-   or any later version published by the Free Software Foundation;
-   with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
-   A copy of the license is included in the section entitled "GNU
-   Free Documentation License".
+###### Timelines
 
-.. _timelines:
-
-Timelines
-*********
-
-.. contents:: Table of content
     :local:
 
-Concept
-=======
+## Concept
 
-From an user point of view
---------------------------
+### From a user point of view
 
-Chill has two objectives :
+Chill has two goals :
 
-* make the administrative tasks more lightweight ;
+* it makes the administrative tasks more lightweight ;
 * help social workers to have all information they need to work
 
-To reach this second objective, Chill provides a special view: **timeline**. On a timeline view, information is gathered and shown on a single page, from the most recent event to the oldest one.
+To reach this second goal, Chill provides a special view: **timeline**. On a timeline view, information is gathered and shown on a single page, from the most recent event to the oldest one.
 
 The information gathered is linked to a *context*. This *context* may be, for instance :
 
-* a person : events linked to this person are shown on the page ;
+* a person: events linked to this person are shown on the page ;
 * a center: events linked to a center are shown. They may concern different peoples ;
 * ...
 
-In other word, the *context* is the kind of argument that will be used in the event's query.
+In another word, the *context* is the kind of argument that will be used in the event's query.
 
 Let us recall that only the data the user has allowed to see should be shown.
 
-.. seealso::
+   [The issue where the subject was first discussed ](https://redmine.champs-libres.coop/issues/224)
 
-   `The issue where the subject was first discussed <https://redmine.champs-libres.coop/issues/224>`_
-
-
-For developers
---------------
+### For developers
 
 The `Main` bundle provides interfaces and services to help to build timelines.
 
@@ -51,45 +33,38 @@ If a bundle wants to *push* information in a timeline, it should be create a ser
 
 If a bundle wants to provide a new context for a timeline, the service `chill.main.timeline_builder` will helps to gather timeline's services supporting the defined context, and run queries across the models.
 
-.. _understanding-queries :
-
-Understanding queries
-^^^^^^^^^^^^^^^^^^^^^
+##### Understanding queries
 
 Due to the fact that timelines should show only the X last events from Y differents tables, queries for a timeline may consume a lot of resources: at first on the database, and then on the ORM part, which will have to deserialize DB data to PHP classes, which may not be used if they are not part of the "last X events".
 
-To avoid such load on database, the objects are queried in two steps :
+To avoid such a load on a database, the objects are queried in two steps :
 
-1. An UNION request which gather the last X events, ordered by date. The data retrieved are the ID, the date, and a string key: a type. This type discriminates the data type.
-2. The PHP objects are queried by ID, the type helps the program to link id with the kind of objects.
+1. A UNION request that gathers the last X events, ordered by date. The data retrieved are the ID, the date, and a string key: a type. This type discriminates the data type.
+2. ID queries the PHP objects, the type helps the program to link id with the kind of objects.
 
-Those methods should ensure that only X PHP objects will be gathered and build by the ORM.
+Those methods should ensure that only X PHP objects will be gathered and built by the ORM.
 
-What does the master timeline builder service ?
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+##### What does the master timeline builder service?
 
  When the service `chill.main.timeline_builder` is instanciated, the service is informed of each service taggued with `chill.timeline` tags. Then,
 
 1. The service build an UNION query by assembling column and tables names provided by the `fetchQuery` result ;
-2. The UNION query is run, the result contains an id and a type for each row (see :ref:`above <understanding-queries>`)
+2. The UNION query is run, the result contains an id and a type for each row (see [above ](understanding-queries.md))
 3. The master service gather all id with the same type. Then he searches for the `chill.timeline`'s service which will be able to get the entities. Then, the entities will be fetched using the `fetchEntities` function. All entities are gathered in one query ;
 4. The information to render entities in HTML is gathered by passing entity, one by one, on `getEntityTemplate` function.
 
-Pushing events to a timeline
-=============================
+## Pushing events to a timeline
 
 To push events on a timeline :
 
 1. Create a class which implements `Chill\MainBundle\Timeline\TimelineProviderInterface` ;
 2. Define the class as a service, and tag the service with `chill.timeline`, and define the context associated with this timeline (you may add multiple tags for different contexts).
 
-Implementing the TimelineProviderInterface
-------------------------------------------
+### Implementing the TimelineProviderInterface
 
 The has the following signature :
 
-.. code-block:: php
-
+```php
     namespace Chill\MainBundle\Timeline;
 
     interface TimelineProviderInterface
@@ -135,7 +110,6 @@ The has the following signature :
          * - `template` : the template FQDN
          * - `template_data`: the data required by the template
          *
-         *
          * Example:
          *
          * ```
@@ -160,51 +134,42 @@ The has the following signature :
         public function getEntityTemplate($entity, $context, array $args);
 
     }
+```
 
+##### The `fetchQuery` function
 
-The `fetchQuery` function
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The fetchQuery function help to build the UNION query to gather events. This function should return an instance of :code:`TimelineSingleQuery`. For you convenience, this object may be build using an associative array with the following keys:
+The fetchQuery function helps to build the UNION query to gather events. This function should return an instance of `TimelineSingleQuery`. For you convenience, this object may be build using an associative array with the following keys:
 
 * `id` : the name of the id column
 * `type`: a string to indicate the type
 * `date`: the name of the datetime column, used to order entities by date
-* `FROM`: the FROM clause. May contains JOIN instructions
+* `FROM`: the FROM clause. May contain JOIN instructions
 * `WHERE`: the WHERE clause;
 * `parameters`: the parameters to pass to the query
 
-The parameters should be replaced into the query by :code:`?`. They will be replaced into the query using prepared statements.
+The parameters should be replaced into the query by `?`. They will be replaced into the query using prepared statements.
 
 `$context` and `$args` are defined by the bundle which will call the timeline rendering. You may use them to build a different query depending on this context.
 
 For instance, if the context is `'person'`, the args will be this array :
 
-.. code-block:: php
-
     array(
         'person' => $person //a \Chill\PersonBundle\Entity\Person entity
     );
 
-For the context :code:`center`, the args will be:
-
-.. code-block:: php
+For the context `center`, the args will be:
 
     array(
         'centers' => [ ]  // an array of \Chill\MainBundle\Entity\Center entities
     );
 
-
 You should find in the bundle documentation which contexts are arguments the bundle defines.
 
-.. note::
-
     We encourage to use `ClassMetaData` to define column names arguments. If you change your column names, changes will be reflected automatically during the execution of your code.
 
 Example of an implementation :
 
-.. code-block:: php
-
+```php
     namespace Chill\ReportBundle\Timeline;
 
     use Chill\MainBundle\Timeline\TimelineProviderInterface;
@@ -250,19 +215,16 @@ Example of an implementation :
 
         //....
 
-
     }
+```
 
-The `supportsType` function
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+##### The `supportsType` function
 
-This function indicate to the master `chill.main.timeline_builder` service (which orchestrate the build of UNION queries) that the service supports the type indicated in the result's array of the `fetchQuery` function.
+This function indicates to the master `chill.main.timeline_builder` service (which orchestrate the build of UNION queries) that the service supports the type indicated in the result's array of the `fetchQuery` function.
 
 The implementation of our previous example will be :
 
-.. code-block:: php
-
-
+```php
     namespace Chill\ReportBundle\Timeline;
 
     use Chill\MainBundle\Timeline\TimelineProviderInterface;
@@ -284,16 +246,15 @@ The implementation of our previous example will be :
 
         //...
     }
+```
 
-The `getEntities` function
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
+##### The `getEntities` function
 
 This is where the service must fetch entities from database and return them to the master service.
 
 The results **must be** an array where the id given by the UNION query (remember `fetchQuery`).
 
-.. code-block:: php
-
+```php
     namespace Chill\ReportBundle\Timeline;
 
     use Chill\MainBundle\Timeline\TimelineProviderInterface;
@@ -316,9 +277,9 @@ The results **must be** an array where the id given by the UNION query (remember
         }
 
     }
+```
 
-The `getEntityTemplate` function
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+##### The `getEntityTemplate` function
 
 This is where the master service will collect information to render the entity.
 
@@ -329,8 +290,7 @@ The result must be an associative array with :
 
 Example :
 
-.. code-block:: php
-
+```php
     array(
         'template' => 'ChillMyBundle:timeline:template.html.twig',
         'template_data' => array(
@@ -338,23 +298,19 @@ Example :
             'person' => $args['person']
             )
         );
+```
 
-The template must, obviously, exists. Example :
-
-.. code-block:: jinja
+The template must exist. Example :
 
     <p><i class="fa fa-folder-open"></i>&nbsp;{{ 'An accompanying period is opened for %person% on %date%'|trans({'%person%': person, '%date%': period.dateOpening|localizeddate('long', 'none') } ) }}</p>
 
-
-Create a timeline with his own context
-======================================
+## Create a timeline with his own context
 
 You have to create a Controller which will execute the service `chill.main.timeline_builder`. Using the `Chill\MainBundle\Timeline\TimelineBuilder::getTimelineHTML` function, you will get an HTML representation of the timeline, which you may include with twig `raw` filter.
 
 Example :
 
-.. code-block:: php
-
+```php
     namespace Chill\PersonBundle\Controller;
 
     use Symfony\Component\HttpFoundation\Response;
@@ -384,3 +340,4 @@ Example :
         }
 
     }
+```

docs/source/development/useful-snippets.md

@@ -1,26 +1,17 @@
+# Useful snippets
 
+###### Dependency Injection
 
-
-
-Useful snippets
-###############
-
-Dependency Injection
-********************
-
-Configure route automatically
-=============================
+## Configure route automatically
 
 Add the route for the current bundle automatically on the main app.
 
-.. code-block:: php
-
+```php
     namespace Chill\MyBundle\DependencyInjection;
 
     use Symfony\Component\DependencyInjection\ContainerBuilder;
     use Symfony\Component\DependencyInjection\Extension\PrependExtensionInterface;
 
-
     class ChillMyExtension extends Extension implements PrependExtensionInterface
     {
         // ...
@@ -30,8 +21,8 @@ Add the route for the current bundle automatically on the main app.
             $this->prependRoutes($container);
 
         }
-            
-        public function prependRoutes(ContainerBuilder $container) 
+
+        public function prependRoutes(ContainerBuilder $container)
         {
             //add routes for custom bundle
              $container->prependExtensionConfig('chill_main', array(
@@ -42,32 +33,26 @@ Add the route for the current bundle automatically on the main app.
                )
             ));
         }
+```
 
+###### Security
 
-Security
-********
-
-Get the circles a user can reach
-================================
-
-.. code-block:: php
+## Get the circles a user can reach
 
+```php
    use Symfony\Component\Security\Core\Role\Role;
 
    $authorizationHelper = $this->get('chill.main.security.authorization.helper');
    $circles = $authorizationHelper
        ->getReachableCircles(
              $this->getUser(), # from a controller
-             new Role('CHILL_ROLE'), 
-             $center 
+             new Role('CHILL_ROLE'),
+             $center
        );
+```
 
+###### Controller
 
-Controller
-**********
+## Secured controller for person
 
-Secured controller for person
-=============================
-
-.. literalinclude:: useful-snippets/controller-secured-for-person.php
-   :language: php
+   [controller](useful-snippets/controller-secured-for-person.php)

docs/source/development/user-interface/css-classes.md

@@ -0,0 +1,63 @@
+Permission is granted to copy, distribute and/or modify this document
+   under the terms of the GNU Free Documentation License, Version 1.3
+   or any later version published by the Free Software Foundation;
+   with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+   A copy of the license is included in the section entitled "GNU
+   Free Documentation License".
+
+# CSS classes and mixins
+
+The stylesheet are based on the framework [ScratchCSS ](https://github.com/Champs-Libres/ScratchCSS).
+
+We added some useful classes and mixins for the Chill usage.
+
+###### CSS Classes
+
+## Statement "empty data"
+
+CSS Selector
+   `.chill-no-data-statement`
+In which case will you use this selector ?
+   When a list is empty, and a message fill the list to inform that the data is empty
+Example usage
+   ```jinja
+   <span class="chill-no-data-statement">{{ 'No reason associated'|trans }}</span>
+   ```
+
+## Quotation of user text
+
+CSS Selector
+   `blockquote.chill-user-quote`
+In which case will you use this selector ?
+   When you quote text that were filled by the user in a form.
+Example usage
+   ```jinja
+   <blockquote class="chill-user-quote">{{ entity.remark|nl2br }}</blockquote>
+   ```
+
+## Boxes
+
+CSS Selector
+   `chill__box`
+In which case will you use this selector ?
+   When displaying some data in a nice box
+Example usage
+   ```html
+   <span class="chill__box green">A nice box with green background</span>
+   <span class="chill__box red">A nice box with red background</span>
+   ```
+
+###### Mixins
+
+## Entity decorator
+
+Mixin
+   `@mixin entity($background-color, $color: white)`
+In which case including this mixin ?
+   When you create a `sticker`, a sort of label to represent a text in a way that the user can associate immediatly with a certain type of class / entity.
+Example usage
+   ```sass
+      span.entity.entity-activity.activity-reason {
+          @include entity($chill-pink, white);
+      }
+```

docs/source/development/user-interface/js-functions.md

@@ -0,0 +1,234 @@
+Permission is granted to copy, distribute and/or modify this document
+   under the terms of the GNU Free Documentation License, Version 1.3
+   or any later version published by the Free Software Foundation;
+   with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+   A copy of the license is included in the section entitled "GNU
+   Free Documentation License".
+
+# Javascript functions
+
+Some function may be useful to manipulate elements on the page.
+
+###### Show-hide elements according to a form state
+
+The module ``ShowHide`` will allow you to show/hide part of your page using a specific test.
+
+This must be use inside a javascript module.
+
+## Usage
+
+In this module, the module will listen to all input given in the ``container_from`` div, and will show or hide the content of the ``container_target`` according to the result of the ``test`` function.
+
+		<div id="container_from">
+			{{ form_row(form.accompagnementRQTHDate) }}
+		</div>
+		
+		<div id="container_target">
+			{{ form_row(form.accompagnementComment) }}
+		</div>
+
+    import { ShowHide } from 'ShowHide/show_hide.js';
+
+    var 
+        from = document.getElementById("container_from"),
+        target = document.getElementById("container_target")
+        ;
+
+    new ShowHide({
+        froms: [from], // the value of from should be an iterable
+        container: [target], // the value of container should be an iterable
+        test: function(froms, event) {
+            // iterate over each element of froms
+            for (let f of froms.values()) {
+                // get all input inside froms
+                for (let input of f.querySelectorAll('input').values()) {
+                    if (input.value === 'autre') {
+                        return input.checked;
+                    }
+                }
+            }
+
+            return false;
+        }
+    });
+
+Once instantiated, the class ``ShowHide`` will:
+
+1. get all input from each element inside the ``froms`` values
+2. attach an event listener (by default, ``change``) to each input inside each entry in ``froms``
+3. each time the event is fired, launch the function ``test``
+4. show the element in the container given in ``container``, if the result of ``test`` is true, or hide them otherwise.
+
+The test is also launched when the page is loaded.
+
+## Show/hide while the user enter data: using the ``input`` event
+
+One can force to use another event on the input elements, instead of the default ``'change'`` event. 
+
+For achieving this, use the `event_name` option.
+
+    new ShowHide({
+        froms: froms,
+        test: test_function,
+        container: containers ,
+        // using this option, we use the event `input` instead of `change`
+        event_name: 'input'
+    });
+
+### Examples
+
+   :language: javascript
+
+## Using Show/Hide in collections forms
+
+Using show / hide in collection forms implies: 
+
+* to launch show/hide manually for each entry when the page is loaded ; 
+* to catch when an entry is added to the form ;
+
+As the show/hide is started manually and not on page load, we add the option ``load_event: null`` to the options: 
+
+   new ShowHide({
+     load_event: null,
+     froms: [ from ],
+     container: [ container ],
+     test: my_test_function
+   });
+
+   When using ``load_event: null`` inside the options, the value of event will be ``null`` as second argument for the test function.
+
+   ```javascript
+      my_test_function(froms, event) {
+          // event will be null on first launch
+      }
+```
+
+Example usage: here, we would like to catch for element inside a CV form, where the user may add multiple formation entries.
+
+   import { ShowHide } from 'ShowHide/show_hide.js';
+
+   // we factorize the creation of show hide element in this function.
+   var make_show_hide = function(entry) {
+       let
+           obtained = entry.querySelector('[data-diploma-obtained]'),
+           reconnue = entry.querySelector('[data-diploma-reconnue]')
+       ;
+       new ShowHide({
+           load_event: null,
+           froms: [ obtained ],
+           container: [ reconnue ],
+           test: my_test_function
+       });
+   };
+
+   // this code is fired when an entry is added on the page
+   window.addEventListener('collection-add-entry', function(e) {
+       // if the form contains multiple collection, we filter them here:
+       if (e.detail.collection.dataset.collectionName === 'formations') {
+           make_show_hide(e.detail.entry);
+       }
+   });
+
+   // on page load, we create a show/hide 
+   window.addEventListener('load', function(_e) {
+       let
+           formations = document.querySelectorAll('[data-formation-entry]')
+           ;
+
+       for (let f of formations.values()) {
+           make_show_hide(f);
+       }
+   });
+
+## Handling encapsulated show/hide elements
+
+This module allow to handle encapsulated show/hide elements. For instance :
+
+* in a first checkbox list, a second checkbox list is shown if some element is checked ;
+* in this second checkbox list, a third input is shown if some element is checked inside the second checkbox list.
+
+As a consequence, if the given element in the first checkbox list is unchecked, the third input must also be hidden.
+
+Example: when a situation professionnelle is ``en activite``, the second element ``type contrat`` must be shown if ``en_activite`` is checked. Inside ``type_contrat``, ``type_contrat_aide`` should be shown when ``contrat_aide`` is checked.
+
+        <div id="situation_prof">
+            <input type="radio" name="situationProfessionnelle" value="" checked="checked" />
+            <input type="radio" name="situationProfessionnelle" value="sans_emploi" />
+            <input type="radio" name="situationProfessionnelle" value="en_activite" />
+        </div>
+        
+        
+        <div id="type_contrat">
+            <input type="checkbox" name="typeContrat[]" value="cdd" /> 
+            <input type="checkbox" name="typeContrat[]" value="cdi" />
+            <input type="checkbox" name="typeContrat[]" value="contrat_aide" />
+        </div>
+        
+        <div id="type_contrat_aide">
+            <input type="text" name="typeContratAide" />
+        </div>
+
+The JS code will be:
+
+   import { ShowHide } from 'ShowHide/show_hide.js';
+   // we search for the element within the DOM
+   // NOTE: all the elements should be searched before instanciating the showHides. 
+   // if not, the elements **may** have disappeared from the DOM
+
+   var
+       situation_prof = document.getElementById('situation_prof'),
+       type_contrat = document.getElementById('type_contrat'),
+       type_contrat_aide = document.getElementById('type_contrat_aide'),
+       ;
+
+   // the first show/hide will apply on situation_prof
+   new ShowHide({
+       // the id will help us to keep a track of the element
+       id: 'situation_prof_type_contrat',
+       froms: [situation_prof],
+       container: [type_contrat],
+       test: function(froms) {
+           for (let f of froms.values()) {
+               for (let input of f.querySelectorAll('input').values()) {
+                   if (input.value === 'en_activite') {
+                       return input.checked;
+                   }
+               }
+           }
+           
+           return false;
+       }
+   });
+
+   // the show/hide will apply on "contrat aide"
+   var show_hide_contrat_aide = new ShowHide({
+       froms: [type_contrat],
+       container: [type_contrat_aide],
+       test: function(froms) {
+           for (let f of froms.values()) {
+               for (let input of f.querySelectorAll('input').values()) {
+                   if (input.value === 'contrat_aide') {
+                       return input.checked;
+                   }
+               }
+           }
+           
+           return false;
+       }
+   });
+
+   // we handle here the case when the first show-hide is changed: the third input must also disappears
+   window.addEventListener('show-hide-hide', function (e) {
+       if (e.detail.id = 'situation_prof_type_contrat') {
+           // we force the 3rd element to disappears
+           show_hide_contrat_aide.forceHide();
+       }
+   });
+
+   // when the first show-hide is changed, it makes appears the second one.
+   // we check here that the second show-hide is processed.
+   window.addEventListener('show-hide-show', function (e) {
+       if (e.detail.id = 'situation_prof_type_contrat') {
+           show_hide_contrat_aide.forceCompute();
+       }
+   });

docs/source/development/user-interface/layout-template-usage.md

@@ -0,0 +1,196 @@
+Permission is granted to copy, distribute and/or modify this document
+   under the terms of the GNU Free Documentation License, Version 1.3
+   or any later version published by the Free Software Foundation;
+   with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+   A copy of the license is included in the section entitled "GNU
+   Free Documentation License".
+
+# Layout / Template usage
+
+We recommand the use of the existing layouts to ensure the consistency of the design. This section explains the different templates and how to use it.
+
+The layouts are twig templates.
+
+## Twig templating helper
+
+### `chill_print_or_message`
+
+Print a value or use a default template if the value is empty.
+
+The template can be customized.
+
+Two default templates are registered:
+
+- `default`, do not decorate the value ;
+- `blockquote`: wrap the value into a blockquote if exists
+
+  {{ "This is a message"|chill_print_or_message("No message") }}
+  <!-- will print "This is a message" -->
+
+  {{ ""|chill_print_or_message("No message")}}
+  <!-- will print <span class="chill-no-data-statement">No message</span> -->
+
+  {{ "This is a comment\n with multiples lines"|chill_print_or_message("No comment", 'blockquote') }}
+  <!-- will print <blockquote class="chill-user-quote">This is a comment<br/>with multiples lines</blockquote> -->
+
+When customizing the template, two arguments are passed to the template:
+
+- `value`: the actual value ;
+- `message`: the message, given as argument
+
+### Routing with return path
+
+Three twig function are available for creating routes and handling "return path".
+
+**Rationale**: When building a "CRUD" (CReate, Update, Delete of an entity), you would like to allow people to go back on some custom cancel page when coming for another place of an application. For instance, if you are in the timeline and show an activity, you would like that the user go back to the timeline when pressing the "return" button at the bottom of the page, instead of going back to the "activity list" page.
+
+Using those function, a `returnPath` parameter will be added in the path generated. It will be used instead of the default one in the subsequente pages.
+
+- `chill_path_add_return_path(name, parameters = [], relative = false)`: will create a path with current page as return path (users will go back to the current page on the next page) ;
+- `chill_return_path_or(name, parameters = [], relative = false)`: will create a path to the return path if present, or build the path according to the given parameters ;
+- `chill_path_forward_return_path(name, parameters = [], relative = false)`: will create a path and adding the return path that is present for the current page, *forwarding* the return path to the next page. This is useful if you are on a "show" page with a return path (by instance, the "timeline" page), you place a link to the *edit* page and want users to go back to the "timeline" page on the edit page.
+
+- `chill_return_path_or`:
+
+## Organisation of the layouts
+
+### ChillMainBundle::layout.html.twig
+
+This is the base layout. It includes the most import css / js files. It display a page with
+
+* a horizontal navigation menu
+* a place for content
+* a footer
+
+The layout containts blocks, that are :
+
+* title
+
+  * to display title
+
+* css
+
+  * where to add some custom css
+
+* navigation_section_menu
+
+  * place where to insert the section menu in the navigation menu (by default the navigation menu is inserted)
+
+* navigation_search_bar
+
+  * place where to insert a search bar in the navigation menu (by default the search bar is inserted)
+
+* top_banner
+
+  * place where to display a banner below the navigation menu (this place is use to display the details of the person)
+
+* sublayout_containter
+
+  * place between the header and the footer that can be used to create a new layout (with vertical menu for example)
+
+* content
+
+  * place where to display the content (flash message are included outside of this block)
+
+* js
+
+  * where to add some custom javascript
+
+### ChillMainBundle::layoutWithVerticalMenu.html.twig
+
+This layout extends `ChillMainBundle::layout.html.twig`. It replaces the block `layout_content` and divides this block for displaying a vertical menu and some content.
+
+It proposes 2 new blocks :
+
+* layout_wvm_content
+
+  * where to display the page content
+
+* vertical_menu_content
+
+  * where to place the vertical menu
+
+### ChillMainBundle::Admin/layout.html.twig
+
+This layout extends `ChillMainBundle::layout.html.twig`. It hides the search bar, remplaces the `section menu` with the `admin section menu`.
+
+It proposes a new block :
+
+* admin_content
+
+  * where to display the admin content
+
+### ChillMainBundle::Admin/layoutWithVerticalMenu.html.twig
+
+This layout extends `ChillMainBundle::layoutWithVerticalMenu.html.twig`. It do the same changes than `ChillMainBundle::Admin/layout.html.twig` : hiding the search bar, remplacing the `section menu` with the `admin section menu`.
+
+It proposes a new block :
+
+* admin_content
+
+  * where to display the admin content
+
+@ChillPersonBundle/Person/layout.html.twig
+-----------------------------------
+
+This layout extend `ChillMainBundle::layoutWithVerticalMenu.html.twig` add the person details in the block `top_banner`, set the menu `person` as the vertical menu.
+
+It proposes 1 new block :
+
+* content
+
+  * where to display the information of the person
+
+### ChillMainBundle::Export/layout.html.twig
+
+This layout extends `ChillMainBundle::layoutWithVerticalMenu.html.twig` and set the menu `export` as the vertical menu.
+
+It proposes 1 new block :
+
+* export_content
+
+  * where to display the content of the export
+
+## Useful template and helpers
+
+### Macros
+
+Every bundle may bring their own macro to print resources with uniformized styles.
+
+See :
+
+- [Macros in person bundle ](person-bundle-macros.md) ;
+- [Macros in activity bundle ](activity-bundle-macros.md) ;
+- [Macros in group bundle ](group-bundle-macros.md) ;
+- [Macros in main bundle ](main-bundle-macros.md) ;
+
+### Templates
+
+##### ChillMainBundle::Util:confirmation_template.html.twig
+
+This template show a confirmation template before making dangerous things. You can add your own message and title, or define those message by yourself in another template.
+
+The accepted parameters are :
+
+- `title` (string) a title for the page. Not mandatory (it won't be rendered if not defined)
+- `confirm_question` (string) a confirmation question. This question will not be translated into the template, and may be printed as raw. Not mandatory (it won't be rendered if not defined)
+- `form` : (:class:`Symfony\Component\Form\FormView`) a form wich **must** contains an input named `submit`, which must be a :class:`Symfony\Component\Form\Extension\Core\Type\SubmitType`. Mandatory
+- `cancel_route` : (string) the name of a route if the user want to cancel the action
+- `cancel_parameters` (array) the parameters for the route defined in `cancel_route`
+
+Usage :
+
+       {{ include('ChillMainBundle:Util:confirmation_template.html.twig',
+           {
+               # a title, not mandatory
+               'title'             : 'Remove membership'|trans,
+               # a confirmation question, not mandatory
+               'confirm_question'  : 'Are you sure you want to remove membership ?'|trans
+               # a route for "cancel" button (mandatory)
+               'cancel_route'      : 'chill_group_membership_by_person',
+               # the parameters for 'cancel' route (default to {} )
+               'cancel_parameters' : { 'person_id' : membership.person.id },
+               # the form which will send the deletion. This form
+               # **must** contains a SubmitType
+               'form'              : form
+           } ) }}

docs/source/development/user-interface/rst/css-classes.rst

@@ -10,7 +10,7 @@
 CSS classes and mixins
 ######################
 
-The stylesheet are based on the framework `ScratchCSS <https://github.com/Champs-Libres/ScratchCSS>`_. 
+The stylesheet are based on the framework `ScratchCSS <https://github.com/Champs-Libres/ScratchCSS>`_.
 
 We added some useful classes and mixins for the Chill usage.
 
@@ -22,12 +22,12 @@ Statement "empty data"
 ======================
 
 CSS Selector
-   :code:`.chill-no-data-statement`
+   `.chill-no-data-statement`
 In which case will you use this selector ?
    When a list is empty, and a message fill the list to inform that the data is empty
 Example usage
    .. code-block:: html+jinja
-      
+
       <span class="chill-no-data-statement">{{ 'No reason associated'|trans }}</span>
 
 
@@ -35,7 +35,7 @@ Quotation of user text
 =======================
 
 CSS Selector
-   :code:`blockquote.chill-user-quote`
+   `blockquote.chill-user-quote`
 In which case will you use this selector ?
    When you quote text that were filled by the user in a form.
 Example usage
@@ -47,7 +47,7 @@ Boxes
 =====
 
 CSS Selector
-   :code:`chill__box`
+   `chill__box`
 In which case will you use this selector ?
    When displaying some data in a nice box
 Example usage
@@ -66,7 +66,7 @@ Entity decorator
 =================
 
 Mixin
-   :code:`@mixin entity($background-color, $color: white)`
+   `@mixin entity($background-color, $color: white)`
 In which case including this mixin ?
    When you create a `sticker`, a sort of label to represent a text in a way that the user can associate immediatly with a certain type of class / entity.
 Example usage

docs/source/development/user-interface/rst/layout-template-usage.rst

@@ -22,28 +22,28 @@ Twig templating helper
 
 Print a value or use a default template if the value is empty.
 
-The template can be customized. 
+The template can be customized.
 
-Two default templates are registered: 
+Two default templates are registered:
 
-- :code:`default`, do not decorate the value ;
-- :code:`blockquote`: wrap the value into a blockquote if exists
+- `default`, do not decorate the value ;
+- `blockquote`: wrap the value into a blockquote if exists
 
 .. code-block:: html+twig
 
-  {{ "This is a message"|chill_print_or_message("No message") }} 
+  {{ "This is a message"|chill_print_or_message("No message") }}
   <!-- will print "This is a message" -->
 
-  {{ ""|chill_print_or_message("No message")}} 
+  {{ ""|chill_print_or_message("No message")}}
   <!-- will print <span class="chill-no-data-statement">No message</span> -->
 
-  {{ "This is a comment\n with multiples lines"|chill_print_or_message("No comment", 'blockquote') }} 
+  {{ "This is a comment\n with multiples lines"|chill_print_or_message("No comment", 'blockquote') }}
   <!-- will print <blockquote class="chill-user-quote">This is a comment<br/>with multiples lines</blockquote> -->
 
-When customizing the template, two arguments are passed to the template: 
+When customizing the template, two arguments are passed to the template:
 
-- :code:`value`: the actual value ;
-- :code:`message`: the message, given as argument
+- `value`: the actual value ;
+- `message`: the message, given as argument
 
 Routing with return path
 ------------------------
@@ -52,14 +52,14 @@ Three twig function are available for creating routes and handling "return path"
 
 **Rationale**: When building a "CRUD" (CReate, Update, Delete of an entity), you would like to allow people to go back on some custom cancel page when coming for another place of an application. For instance, if you are in the timeline and show an activity, you would like that the user go back to the timeline when pressing the "return" button at the bottom of the page, instead of going back to the "activity list" page.
 
-Using those function, a :code:`returnPath` parameter will be added in the path generated. It will be used instead of the default one in the subsequente pages. 
+Using those function, a `returnPath` parameter will be added in the path generated. It will be used instead of the default one in the subsequente pages.
 
-- :code:`chill_path_add_return_path(name, parameters = [], relative = false)`: will create a path with current page as return path (users will go back to the current page on the next page) ;
-- :code:`chill_return_path_or(name, parameters = [], relative = false)`: will create a path to the return path if present, or build the path according to the given parameters ;
-- :code:`chill_path_forward_return_path(name, parameters = [], relative = false)`: will create a path and adding the return path that is present for the current page, *forwarding* the return path to the next page. This is useful if you are on a "show" page with a return path (by instance, the "timeline" page), you place a link to the *edit* page and want users to go back to the "timeline" page on the edit page. 
+- `chill_path_add_return_path(name, parameters = [], relative = false)`: will create a path with current page as return path (users will go back to the current page on the next page) ;
+- `chill_return_path_or(name, parameters = [], relative = false)`: will create a path to the return path if present, or build the path according to the given parameters ;
+- `chill_path_forward_return_path(name, parameters = [], relative = false)`: will create a path and adding the return path that is present for the current page, *forwarding* the return path to the next page. This is useful if you are on a "show" page with a return path (by instance, the "timeline" page), you place a link to the *edit* page and want users to go back to the "timeline" page on the edit page.
 
 
-- :code:`chill_return_path_or`: 
+- `chill_return_path_or`:
 
 
 Organisation of the layouts
@@ -178,9 +178,9 @@ Useful template and helpers
 Macros
 ------
 
-Every bundle may bring their own macro to print resources with uniformized styles. 
+Every bundle may bring their own macro to print resources with uniformized styles.
 
-See : 
+See :
 
 - :ref:`Macros in person bundle <person-bundle-macros>` ;
 - :ref:`Macros in activity bundle <activity-bundle-macros>` ;
@@ -195,7 +195,7 @@ ChillMainBundle::Util:confirmation_template.html.twig
 
 This template show a confirmation template before making dangerous things. You can add your own message and title, or define those message by yourself in another template.
 
-The accepted parameters are : 
+The accepted parameters are :
 
 - `title` (string) a title for the page. Not mandatory (it won't be rendered if not defined)
 - `confirm_question` (string) a confirmation question. This question will not be translated into the template, and may be printed as raw. Not mandatory (it won't be rendered if not defined)
@@ -204,7 +204,7 @@ The accepted parameters are :
 - `cancel_parameters` (array) the parameters for the route defined in `cancel_route`
 
 
-Usage : 
+Usage :
 
 
 .. code-block:: html+twig

docs/source/development/user-interface/rst/widgets.rst

@@ -15,12 +15,12 @@ Rationale
 Widgets are useful if you want to publish content on a page provided by another bundle.
 
 
-Examples : 
+Examples :
 
 - you want to publish a list of people on the homepage ;
 - you may want to show the group belonging (see :ref:`group-bundle`) below of the vertical menu, only if the bundle is installed.
 
-The administrator of the chill instance may configure the presence of widget. Although, some widget are defined by default (see :ref:`declaring-widget-by-default`). 
+The administrator of the chill instance may configure the presence of widget. Although, some widget are defined by default (see :ref:`declaring-widget-by-default`).
 
 Concepts
 ========
@@ -71,32 +71,32 @@ Example :
    class AddAPersonWidget implements WidgetInterface
    {
       public function render(
-	 \Twig_Environment $env, 
-	 $place, 
-	 array $context, 
+	 \Twig_Environment $env,
+	 $place,
+	 array $context,
 	 array $config
       ) {
           // this will render a link to the page "add a person"
 	  return $env->render("ChillPersonBundle:Widget:homepage_add_a_person.html.twig");
       }
-   } 
+   }
 
-Arguments are : 
+Arguments are :
 
-- :code:`$env` the :class:`\Twig_Environment`, which you can use to render your widget ;
-- :code:`$place` a string representing the place where the widget is rendered ;
-- :code:`$context` the context given by the template ;
-- :code:`$config` the configuration which is, in this case, always an empty array (see :ref:`creating-a-widget-with-config`).
+- `$env` the :class:`\Twig_Environment`, which you can use to render your widget ;
+- `$place` a string representing the place where the widget is rendered ;
+- `$context` the context given by the template ;
+- `$config` the configuration which is, in this case, always an empty array (see :ref:`creating-a-widget-with-config`).
 
 .. note::
 
-   The html returned by the :code:`render` function will be considered as html safe. You should strip html before returning it. See also `How to escape output in template <http://symfony.com/doc/current/templating/escaping.html>`_.
+   The html returned by the `render` function will be considered as html safe. You should strip html before returning it. See also `How to escape output in template <http://symfony.com/doc/current/templating/escaping.html>`_.
 
 
 Declare your widget
 -------------------
 
-Declare your widget as a service and add it the tag :code:`chill_widget`:
+Declare your widget as a service and add it the tag `chill_widget`:
 
 .. code-block:: yaml
 
@@ -107,17 +107,17 @@ Declare your widget as a service and add it the tag :code:`chill_widget`:
 	       - { name: chill_widget, alias: add_person, place: homepage }
 
 
-The tag must contains those arguments : 
+The tag must contains those arguments :
 
-- :code:`alias`: an alias, which will be used to reference the widget into the config
-- :code:`place`: a place where this widget is authorized
+- `alias`: an alias, which will be used to reference the widget into the config
+- `place`: a place where this widget is authorized
 
 If you want your widget to be available on multiple places, you should add one tag with each place.
 
 Conclusion
 ----------
 
-Once your widget is correctly declared, your widget should be available in configuration. 
+Once your widget is correctly declared, your widget should be available in configuration.
 
 .. code-block:: bash
 
@@ -134,14 +134,14 @@ Once your widget is correctly declared, your widget should be available in confi
 	       # the widget alias (see your installed bundles config). Possible values are (maybe incomplete) : person_list, add_person
 	       widget_alias:         ~ # Required
 
-If you want to add your widget by default, see :ref:`declaring-widget-by-default`. 
+If you want to add your widget by default, see :ref:`declaring-widget-by-default`.
 
 .. _creating-a-widget-with-config:
 
 Creating a widget **with** configuration
 ========================================
 
-You can declare some configuration with your widget, which allow administrators to add their own configuration. 
+You can declare some configuration with your widget, which allow administrators to add their own configuration.
 
 To add some configuration, you will :
 
@@ -153,7 +153,7 @@ To add some configuration, you will :
 Declare your widget class
 -------------------------
 
-Declare your widget. You can use some configuration elements in your process, as used here : 
+Declare your widget. You can use some configuration elements in your process, as used here :
 
 .. literalinclude:: ./widgets/ChillPersonAddAPersonWidget.php
    :language: php
@@ -161,7 +161,7 @@ Declare your widget. You can use some configuration elements in your process, as
 Declare your widget as a service
 --------------------------------
 
-You can declare your widget as a service. Not tag is required, as the service will be defined by the :code:`Factory` during next step.
+You can declare your widget as a service. Not tag is required, as the service will be defined by the `Factory` during next step.
 
 
 .. code-block:: yaml
@@ -187,7 +187,7 @@ The widget factory must implements `Chill\MainBundle\DependencyInjection\Widget\
    :language: php
 
 .. note::
-   You can declare your widget into the container by overriding the `createDefinition` method. By default, this method will return the already existing service definition with the id given by :code:`getServiceId`. But you can create or adapt programmatically the definition. `See the symfony doc on how to do it <http://symfony.com/doc/current/service_container/definitions.html#working-with-a-definition>`_.
+   You can declare your widget into the container by overriding the `createDefinition` method. By default, this method will return the already existing service definition with the id given by `getServiceId`. But you can create or adapt programmatically the definition. `See the symfony doc on how to do it <http://symfony.com/doc/current/service_container/definitions.html#working-with-a-definition>`_.
 
    .. code-block:: php
 
@@ -199,22 +199,22 @@ The widget factory must implements `Chill\MainBundle\DependencyInjection\Widget\
           return $definition;
       }
 
-You must then register your factory into the :code:`Extension` class which provide the place. This is done in the :code: `Bundle` class.
+You must then register your factory into the `Extension` class which provide the place. This is done in the  `Bundle` class.
 
 .. code-block:: php
 
-    # Chill/PersonBundle/ChillPersonBundle.php  
- 
+    # Chill/PersonBundle/ChillPersonBundle.php
+
     use Symfony\Component\HttpKernel\Bundle\Bundle;
     use Symfony\Component\DependencyInjection\ContainerBuilder;
     use Chill\PersonBundle\Widget\PersonListWidgetFactory;
 
     class ChillPersonBundle extends Bundle
     {
-	public function build(ContainerBuilder $container) 
+	public function build(ContainerBuilder $container)
 	{
 	    parent::build($container);
-	    
+
 	    $container->getExtension('chill_main')
 		->addWidgetFactory(new PersonListWidgetFactory());
 	}
@@ -225,7 +225,7 @@ You must then register your factory into the :code:`Extension` class which provi
 Declaring a widget by default
 =============================
 
-Use the ability `to prepend configuration of other bundle <http://symfony.com/doc/current/bundles/prepend_extension.html>`_. A living example here : 
+Use the ability `to prepend configuration of other bundle <http://symfony.com/doc/current/bundles/prepend_extension.html>`_. A living example here :
 
 .. literalinclude:: ./widgets/ChillPersonExtension.php
    :language: php
@@ -237,10 +237,10 @@ Defining a place
 Add your place in template
 --------------------------
 
-A place should be defined by using the :code:`chill_widget` function, which take as argument :
+A place should be defined by using the `chill_widget` function, which take as argument :
 
-- :code:`place` (string) a string defining the place ;
-- :code:`context` (array) an array defining the context.
+- `place` (string) a string defining the place ;
+- `context` (array) an array defining the context.
 
 The context should be documented by the bundle. It will give some information about the context of the page. Example: if the page concerns a people, the :class:`Chill\PersonBundle\Entity\Person` class will be in the context.
 
@@ -262,7 +262,7 @@ Declare configuration for you place
 
 In order to let other bundle, or user, to define the widgets inside the given place, you should open a configuration. You can use the Trait :class:`Chill\MainBundle\DependencyInjection\Widget\AddWidgetConfigurationTrait`, which provide the method `addWidgetConfiguration($place, ContainerBuilder $container)`.
 
-Example : 
+Example :
 
 .. literalinclude:: ./widgets/ChillMainConfiguration.php
    :language: php
@@ -285,11 +285,11 @@ You should also adapt the :class:`DependencyInjection\*Extension` class to add C
 Compile the possible widget using Compiler pass
 -----------------------------------------------
 
-For your convenience, simply extends :class:`Chill\MainBundle\DependencyInjection\Widget\AbstractWidgetsCompilerPass`. This class provides a `doProcess(ContainerBuildere $container, $extension, $parameterName)` method which will do the job for you: 
+For your convenience, simply extends :class:`Chill\MainBundle\DependencyInjection\Widget\AbstractWidgetsCompilerPass`. This class provides a `doProcess(ContainerBuildere $container, $extension, $parameterName)` method which will do the job for you:
 
-- :code:`$container` is the container builder
-- :code:`$extension` is the extension name 
-- :code:`$parameterName` is the name of the parameter which contains the configuration for widgets (see :ref:`the example with ChillMain above <example-chill-main-extension>`.
+- `$container` is the container builder
+- `$extension` is the extension name
+- `$parameterName` is the name of the parameter which contains the configuration for widgets (see :ref:`the example with ChillMain above <example-chill-main-extension>`.
 
 .. code-block:: php
 
@@ -300,10 +300,10 @@ For your convenience, simply extends :class:`Chill\MainBundle\DependencyInjectio
 
    /**
    * Compile the service definition to register widgets.
-   * 
+   *
    */
    class WidgetsCompilerPass extends AbstractWidgetsCompilerPass {
-    
+
        public function process(ContainerBuilder $container)
        {
   	   $this->doProcess($container, 'chill_main', 'chill_main.widgets');

docs/source/development/user-interface/widgets.md

@@ -0,0 +1,270 @@
+Permission is granted to copy, distribute and/or modify this document
+   under the terms of the GNU Free Documentation License, Version 1.3
+   or any later version published by the Free Software Foundation;
+   with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+   A copy of the license is included in the section entitled "GNU
+   Free Documentation License".
+
+# Widgets
+
+## Rationale
+
+Widgets are useful if you want to publish content on a page provided by another bundle.
+
+Examples :
+
+- you want to publish a list of people on the homepage ;
+- you may want to show the group belonging (see [group-bundle[) below of the vertical menu, only if the bundle is installed.
+
+The administrator of the chill instance may configure the presence of widget. Although, some widget are defined by default (see [declaring-widget-by-default](declaring-widget-by-default.md)).
+
+## Concepts
+
+A bundle may define *place(s)* where a widget may be rendered.
+
+In a single *place*, zero, one or more *widget* may be displayed.
+
+Some *widget* may require some *configuration*, and some does not require any configuration.
+
+Example:
+
+===========================================  ========  =============================  =======================================
+Use case                                     place     place defined by...            widget provided by...
+===========================================  ========  =============================  =======================================
+Publishing a list of people on the homepage  homepage  defined by [main-bundle](main-bundle.md)  widget provided by [person-bundle](person-bundle.md)
+===========================================  ========  =============================  =======================================
+
+## Creating a widget without configuration
+
+To add a widget, you should :
+
+- define your widget, implementing :class:`Chill\MainBundle\Templating\Widget\WidgetInterface` ;
+- declare your widget with tag `chill_widget`.
+
+### Define the widget class
+
+Define your widget class by implemeting :class:`Chill\MainBundle\Templating\Widget\WidgetInterface`.
+
+Example :
+
+   namespace Chill\PersonBundle\Widget;
+
+   use Chill\MainBundle\Templating\Widget\WidgetInterface;
+
+   /**
+   * Add a button "add a person"
+   *
+   */
+   class AddAPersonWidget implements WidgetInterface
+   {
+      public function render(
+	 \Twig_Environment $env,
+	 $place,
+	 array $context,
+	 array $config
+      ) {
+          // this will render a link to the page "add a person"
+	  return $env->render("ChillPersonBundle:Widget:homepage_add_a_person.html.twig");
+      }
+   }
+
+Arguments are :
+
+- `$env` the :class:`\Twig_Environment`, which you can use to render your widget ;
+- `$place` a string representing the place where the widget is rendered ;
+- `$context` the context given by the template ;
+- `$config` the configuration which is, in this case, always an empty array (see [creating-a-widget-with-config](creating-a-widget-with-config.md)).
+
+   The html returned by the `render` function will be considered as html safe. You should strip html before returning it. See also `How to escape output in template ](http://symfony.com/doc/current/templating/escaping.html.md)_.
+
+### Declare your widget
+
+Declare your widget as a service and add it the tag `chill_widget`:
+
+   service:
+       chill_person.widget.add_person:
+	   class: Chill\PersonBundle\Widget\AddAPersonWidget
+	   tags:
+	       - { name: chill_widget, alias: add_person, place: homepage }
+
+The tag must contains those arguments :
+
+- `alias`: an alias, which will be used to reference the widget into the config
+- `place`: a place where this widget is authorized
+
+If you want your widget to be available on multiple places, you should add one tag with each place.
+
+### Conclusion
+
+Once your widget is correctly declared, your widget should be available in configuration.
+
+   $ php app/console config:dump-reference chill_main
+   # Default configuration for extension with alias: "chill_main"
+   chill_main:
+	   [...]
+	   # register widgets on place "homepage"
+	   homepage:
+
+	       # the ordering of the widget. May be a number with decimal
+	       order:                ~ # Required, Example: 10.58
+
+	       # the widget alias (see your installed bundles config). Possible values are (maybe incomplete) : person_list, add_person
+	       widget_alias:         ~ # Required
+
+If you want to add your widget by default, see [declaring-widget-by-default`.
+
+## Creating a widget **with** configuration
+
+You can declare some configuration with your widget, which allow administrators to add their own configuration.
+
+To add some configuration, you will :
+
+- declare a widget as defined above ;
+- optionnaly declare it as a service ;
+- add a widget factory, which will add configuration to the bundle which provide the place.
+
+### Declare your widget class
+
+Declare your widget. You can use some configuration elements in your process, as used here :
+
+   :language: php
+
+### Declare your widget as a service
+
+You can declare your widget as a service. Not tag is required, as the service will be defined by the `Factory` during next step.
+
+   services:
+      chill_person.widget.person_list:
+    	  class: Chill\PersonBundle\Widget\PersonListWidget
+	  arguments:
+	      - "@chill.person.repository.person"
+	      - "@doctrine.orm.entity_manager"
+	      - "@chill.main.security.authorization.helper"
+	      - "@security.token_storage"
+      # this widget is defined by the PersonListWidgetFactory
+
+You can eventually skip this step and declare your service into the container through the factory (see above).
+
+### Declare your widget factory
+
+The widget factory must implements `Chill\MainBundle\DependencyInjection\Widget\Factory\WidgetFactoryInterface`. For your convenience, an :class:`Chill\MainBundle\DependencyInjection\Widget\Factory\AbstractWidgetFactory` will already implements some easy method.
+
+   :language: php
+
+   You can declare your widget into the container by overriding the `createDefinition` method. By default, this method will return the already existing service definition with the id given by `getServiceId`. But you can create or adapt programmatically the definition. `See the symfony doc on how to do it ](http://symfony.com/doc/current/service_container/definitions.html#working-with-a-definition.md)_.
+
+   ```php
+      public function createDefinition(ContainerBuilder $containerBuilder, $place, $order, array $config)
+      {
+          $definition = new \Symfony\Component\DependencyInjection\Definition('my\Class');
+          // create or adapt your definition here
+```
+
+          return $definition;
+      }
+
+You must then register your factory into the `Extension` class which provide the place. This is done in the  `Bundle` class.
+
+    # Chill/PersonBundle/ChillPersonBundle.php
+
+    use Symfony\Component\HttpKernel\Bundle\Bundle;
+    use Symfony\Component\DependencyInjection\ContainerBuilder;
+    use Chill\PersonBundle\Widget\PersonListWidgetFactory;
+
+    class ChillPersonBundle extends Bundle
+    {
+	public function build(ContainerBuilder $container)
+	{
+	    parent::build($container);
+
+	    $container->getExtension('chill_main')
+		->addWidgetFactory(new PersonListWidgetFactory());
+	}
+    }
+
+## Declaring a widget by default
+
+Use the ability `to prepend configuration of other bundle ](http://symfony.com/doc/current/bundles/prepend_extension.html). A living example here :
+
+   :language: php
+
+## Defining a place
+
+### Add your place in template
+
+A place should be defined by using the [chill_widget` function, which take as argument :
+
+- `place` (string) a string defining the place ;
+- `context` (array) an array defining the context.
+
+The context should be documented by the bundle. It will give some information about the context of the page. Example: if the page concerns a people, the :class:`Chill\PersonBundle\Entity\Person` class will be in the context.
+
+Example :
+
+   {# an empty context on homepage #}
+   {{ chill_widget('homepage', {} }}
+
+   {# defining a place 'right column' with the person currently viewed
+   {{ chill_widget('right_column', { 'person' : person } }}
+
+### Declare configuration for you place
+
+In order to let other bundle, or user, to define the widgets inside the given place, you should open a configuration. You can use the Trait :class:`Chill\MainBundle\DependencyInjection\Widget\AddWidgetConfigurationTrait`, which provide the method `addWidgetConfiguration($place, ContainerBuilder $container)`.
+
+Example :
+
+   :language: php
+   :emphasize-lines: 17, 30, 32, 52
+   :linenos:
+
+You should also adapt the :class:`DependencyInjection\*Extension` class to add ContainerBuilder and WidgetFactories :
+
+   :language: php
+   :emphasize-lines: 25-39, 48-49, 56
+   :linenos:
+
+- line 25-39: we implements the method required by :class:`Chill\MainBundle\DependencyInjection\Widget\HasWidgetExtensionInterface` ;
+- line 48-49: we record the configuration of widget into container's parameter ;
+- line 56 : we create an instance of :class:`Configuration` (declared above)
+
+### Compile the possible widget using Compiler pass
+
+For your convenience, simply extends :class:`Chill\MainBundle\DependencyInjection\Widget\AbstractWidgetsCompilerPass`. This class provides a `doProcess(ContainerBuildere $container, $extension, $parameterName)` method which will do the job for you:
+
+- `$container` is the container builder
+- `$extension` is the extension name
+- `$parameterName` is the name of the parameter which contains the configuration for widgets (see [the example with ChillMain above ](example-chill-main-extension.md).
+
+   namespace Chill\MainBundle\DependencyInjection\CompilerPass;
+
+   use Symfony\Component\DependencyInjection\ContainerBuilder;
+   use Chill\MainBundle\DependencyInjection\Widget\AbstractWidgetsCompilerPass;
+
+   /**
+   * Compile the service definition to register widgets.
+   *
+   */
+   class WidgetsCompilerPass extends AbstractWidgetsCompilerPass {
+
+       public function process(ContainerBuilder $container)
+       {
+  	   $this->doProcess($container, 'chill_main', 'chill_main.widgets');
+       }
+   }
+
+As explained `in the symfony docs ](http://symfony.com/doc/current/service_container/compiler_passes.html), you should register your Compiler Pass into your bundle :
+
+   namespace Chill\MainBundle;
+
+   use Symfony\Component\HttpKernel\Bundle\Bundle;
+   use Symfony\Component\DependencyInjection\ContainerBuilder;
+   use Chill\MainBundle\DependencyInjection\CompilerPass\WidgetsCompilerPass;
+
+   class ChillMainBundle extends Bundle
+   {
+       public function build(ContainerBuilder $container)
+       {
+	   parent::build($container);
+	   $container->addCompilerPass(new WidgetsCompilerPass());
+       }
+   }

docs/source/index.md

@@ -0,0 +1,54 @@
+# Welcome to Chill documentation!
+
+Chill is a free software for social workers.
+
+Chill relies on the php framework [Symfony](http://symfony.com).
+
+## Let's talk together!
+
+You can talk to developers using the matrix room: [https://app.element.io/#/room/#chill-social-admin:matrix.org](https://app.element.io/#/room/#chill-social-admin:matrix.org)
+
+## Contribute
+
+* [Issue tracker](https://gitlab.com/groups/Chill-project/issues) You may want to dispatch an issue to multiple projects. If you do not know in which project your bug / feature request should be located, use the project Chill-Main.
+
+## User manual
+
+A user manual exists in French and currently focuses on describing the main concept of the software.
+
+[Read (and contribute) to the manual](https://fr.wikibooks.org/wiki/Chill)
+
+## Available bundles
+
+* Chill-app | https://gitlab.com/Chill-project/Chill-app This is the skeleton of the project. It contains only a bit of code but provides plenty of information on the configuration of your instance;
+* Chill-bundles: this repository contains all the main bundles. This means:
+  * MainBundle: the main framework,
+  * PersonBundle: to deal with persons,
+  * CustomFieldsBundle: to add custom fields to some entities,
+  * ActivityBundle: to add activities to people,
+  * AsideActivityBundle: to add annex activities such as meetings/trainings not related to a person,
+  * BudgetBundle: to add budget elements to a person's file,
+  * DocGeneratorBundle: to generate documents from templates,
+  * JobBundle: to add information related to employment/ professional training to a person's file,
+  * ReportBundle: to add a report to a person's file,
+  * EventBundle: to create events and add persons that will be participating,
+  * DocStoreBundle: to store documents to people, but also to other entities,
+  * TaskBundle: to register tasks within a person's file or accompanying course,
+  * ThirdPartyBundle: to register third parties,
+
+You will also found the following projects :
+
+* The website https://chill.social : https://gitlab.com/Chill-project/chill.social
+
+And various projects to build docker containers with Chill.
+
+## Licence
+
+The project is available under the [GNU AFFERO GENERAL PUBLIC LICENSE v3](http://www.gnu.org/licenses/agpl-3.0.html).
+
+This documentation is published under the [GNU Free Documentation License (FDL) v1.3](http://www.gnu.org/licenses/fdl-1.3.html)
+
+---
+
+*Copyright (C) 2014 Champs Libres Cooperative SC
+Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".*

docs/source/index.rst

@@ -1,85 +0,0 @@
-.. chill-doc documentation master file, created by
-   sphinx-quickstart on Sun Sep 28 22:04:08 2014.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
-.. Copyright (C)  2014 Champs Libres Cooperative SCRLFS
-   Permission is granted to copy, distribute and/or modify this document
-   under the terms of the GNU Free Documentation License, Version 1.3
-   or any later version published by the Free Software Foundation;
-   with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
-   A copy of the license is included in the section entitled "GNU
-   Free Documentation License".
-
-Welcome to Chill documentation!
-=====================================
-
-Chill is a free software for social workers.
-
-Chill rely on the php framework `Symfony <http://symfony.com>`_.
-
-Contents of this documentation:
-
-.. toctree::
-   :maxdepth: 2
-
-   installation/index.rst
-   development/index.rst
-   Bundles <bundles/index.rst>
-
-Let's talk together !
-======================
-
-You may talk to developers using the matrix room: `https://app.element.io/#/room/#chill-social-admin:matrix.org`_
-
-Contribute
-==========
-
-
-* `Issue tracker <https://gitlab.com/groups/Chill-project/issues>`_ You may want to dispatch the issue in the multiple projects. If you do not know in which project is located your bug / feature request, use the project Chill-Main.
-
-
-User manual
-===========
-
-An user manual exists in French and currently focuses on describing the main concept of the software.
-
-`Read (and contribute) to the manual <https://fr.wikibooks.org/wiki/Chill>`_
-
-Available bundles
-=================
-
-* Chill-app | https://gitlab.com/Chill-project/Chill-app This is the skeleton of the project. It does contains only few code, but information about configuration of your instance ;
-* Chill-bundle: contains the main bundles, the most used in an instance. This means:
-  * chill-main, the main framework,
-  * Chill Person, to deal with persons,
-  * chill custom fields, to add custom fields to some entities,
-  * chill activity: to add activities to people,
-  * chill report: to add report to people,
-  * chill event: to gather people into events,
-  * chill docs store: to store documents to people, but also entities,
-  * chill task: to register task with people,
-  * chill third party: to register third parties,
-
-You will also found the following projects :
-
-* The website https://chill.social : https://gitlab.com/Chill-project/chill.social
-
-And various project to build docker containers with Chill.
-
-TODO in documentation
-=====================
-
-.. todolist::
-
-Licence
-========
-
-The project is available under the `GNU AFFERO GENERAL PUBLIC LICENSE v3`_.
-
-This documentation is published under the `GNU Free Documentation License (FDL) v1.3`_
-
-
-.. _GNU AFFERO GENERAL PUBLIC LICENSE v3: http://www.gnu.org/licenses/agpl-3.0.html
-.. _GNU Free Documentation License (FDL) v1.3: http://www.gnu.org/licenses/fdl-1.3.html
-

docs/source/installation/document-storage.md

@@ -0,0 +1,74 @@
+# Document storage
+
+You can store a document in two different ways:
+
+- on disk
+- in the cloud, using object storage: currently only [openstack swift ](https://docs.openstack.org/api-ref/object-store/index.html) is supported.
+
+## Comparison
+
+Storing documents within the cloud is particularly suitable for "portable" deployments, like in kubernetes, or within a container
+without having to manage volumes to store documents. But you'll have to subscribe to a commercial offer.
+
+Storing documents on disk is easier to configure but more challenging to manage: if you use container, you will have to
+manager volumes to attach documents on disk. You'll have to do some backup of the directory. If chill is load-balanced (and
+multiple instances of chill are run), you will have to find a way to share the directories in read-write mode for every instance.
+
+## On Disk
+
+Configure Chill like this:
+
+```yaml
+   # file config/packages/chill_doc_store.yaml
+   chill_doc_store:
+       use_driver: local_storage
+       local_storage:
+           storage_path: '%kernel.project_dir%/var/storage'
+```
+
+In this configuration, documents will be stored in [var/storage` within your app directory. But this path can be
+elsewhere on the disk. Be aware that the directory must be writable by the user executing the chill app (php-fpm or www-data).
+
+Documents will be stored in subpathes within that directory. The files will be encrypted, the key is stored in the database.
+
+# In the cloud, using openstack object store
+
+You must subscribe to a commercial offer for an object store.
+
+Chill uses some features to allow documents to be stored in the cloud without being uploaded first to the chill server:
+
+- `Form POST Middelware ](https://docs.openstack.org/swift/latest/api/form_post_middleware.html);
+- [Temporary URL Middelware ](https://docs.openstack.org/swift/latest/api/temporary_url_middleware.html).
+
+A secret key must be generated and configured, and CORS must be configured depending on the domain you will use to serve Chill.
+
+At first, create a container and get the base path to the container. For instance, on OVH, if you create a container named "mychill",
+you will be able to retrieve the base path of the container within the OVH interface, like this:
+
+- base_path: [https://storage.gra.cloud.ovh.net/v1/AUTH_123456789/mychill/` => will be variable `ASYNC_UPLOAD_TEMP_URL_BASE_PATH`
+- container: `mychill` => will be variable `ASYNC_UPLOAD_TEMP_URL_CONTAINER`
+
+You can also generate a key, which should have at least 20 characters. This key will go in the variable `ASYNC_UPLOAD_TEMP_URL_KEY`.
+
+   See the `documentation of symfony ](https://symfony.com/doc/current/configuration.html#config-env-vars) on how to store variables, and how to encrypt them if needed.
+
+Configure the storage like this:
+
+```yaml
+   # file config/packages/chill_doc_store.yaml
+   chill_doc_store:
+       use_driver: openstack
+       openstack:
+           temp_url:
+               temp_url_key:         '%env(resolve:ASYNC_UPLOAD_TEMP_URL_KEY)%'       # Required
+               container:            '%env(resolve:ASYNC_UPLOAD_TEMP_URL_CONTAINER)%' # Required
+               temp_url_base_path:   '%env(resolve:ASYNC_UPLOAD_TEMP_URL_BASE_PATH)%' # Required
+```
+
+Chill is able to configure the container to store a document. Grab an Openstack Token (for instance, using `openstack token issue` or
+the web interface of your openstack provider), and run this command:
+
+   `symfony console async-upload:configure --os_token=OPENSTACK_TOKEN -d https://mychill.mydomain.example`
+
+   # or, without symfony-cli
+   `bin/console async-upload:configure --os_token=OPENSTACK_TOKEN -d https://mychill.mydomain.example`

docs/source/installation/document-storage.rst

@@ -1,84 +0,0 @@
-Document storage
-################
-
-You can store document on two different ways:
-
-- on disk
-- in the cloud, using object storage: currently only `openstack swift <https://docs.openstack.org/api-ref/object-store/index.html>`_ is supported.
-
-Comparison
-==========
-
-Storing documents within the cloud is particularily suitable for "portable" deployments, like in kubernetes, or within container
-without having to manage volumes to store documents. But you'll have to subscribe on a commercial offer.
-
-Storing documents on disk is more easy to configure, but more difficult to manage: if you use container, you will have to
-manager volumes to attach documents on disk. You'll have to do some backup of the directory. If chill is load-balanced (and
-multiple instances of chill are run), you will have to find a way to share the directories in read-write mode for every instance.
-
-On Disk
-=======
-
-Configure Chill like this:
-
-.. code-block:: yaml
-
-   # file config/packages/chill_doc_store.yaml
-   chill_doc_store:
-       use_driver: local_storage
-       local_storage:
-           storage_path: '%kernel.project_dir%/var/storage'
-
-In this configuration, documents will be stored in :code:`var/storage` within your app directory. But this path can be
-elsewhere on the disk. Be aware that the directory must be writable by the user executing the chill app (php-fpm or www-data).
-
-Documents will be stored in subpathes within that directory. The files will be encrypted, the key is stored in the database.
-
-In the cloud, using openstack object store
-##########################################
-
-You must subscribe to a commercial offer for object store.
-
-Chill use some features to allow documents to be stored in the cloud without being uploaded first to the chill server:
-
-- `Form POST Middelware <https://docs.openstack.org/swift/latest/api/form_post_middleware.html>`_;
-- `Temporary URL Middelware <https://docs.openstack.org/swift/latest/api/temporary_url_middleware.html>`_.
-
-A secret key must be generated and configured, and CORS must be configured depending on the domain you will use to serve Chill.
-
-At first, create a container and get the base path to the container. For instance, on OVH, if you create a container named "mychill",
-you will be able to retrieve the base path of the container within the OVH interface, like this:
-
-- base_path: :code:`https://storage.gra.cloud.ovh.net/v1/AUTH_123456789/mychill/` => will be variable :code:`ASYNC_UPLOAD_TEMP_URL_BASE_PATH`
-- container: :code:`mychill` => will be variable :code:`ASYNC_UPLOAD_TEMP_URL_CONTAINER`
-
-You can also generate a key, which should have at least 20 characters. This key will go in the variable :code:`ASYNC_UPLOAD_TEMP_URL_KEY`.
-
-.. note::
-
-   See the `documentation of symfony <https://symfony.com/doc/current/configuration.html#config-env-vars>`_ on how to store variables, and how to encrypt them if needed.
-
-Configure the storage like this:
-
-.. code-block:: yaml
-
-   # file config/packages/chill_doc_store.yaml
-   chill_doc_store:
-       use_driver: openstack
-       openstack:
-           temp_url:
-               temp_url_key:         '%env(resolve:ASYNC_UPLOAD_TEMP_URL_KEY)%'       # Required
-               container:            '%env(resolve:ASYNC_UPLOAD_TEMP_URL_CONTAINER)%' # Required
-               temp_url_base_path:   '%env(resolve:ASYNC_UPLOAD_TEMP_URL_BASE_PATH)%' # Required
-
-Chill is able to configure the container in order to store document. Grab an Openstack Token (for instance, using :code:`openstack token issue` or
-the web interface of your openstack provider), and run this command:
-
-.. code-block:: bash
-
-   symfony console async-upload:configure --os_token=OPENSTACK_TOKEN -d https://mychill.mydomain.example
-
-   # or, without symfony-cli
-   bin/console async-upload:configure --os_token=OPENSTACK_TOKEN -d https://mychill.mydomain.example
-
-

docs/source/installation/enable-collabora-for-dev.md

@@ -0,0 +1,103 @@
+## Enable CODE for development
+
+For editing a document, there must be a way to communicate between the collabora server and the symfony server, in
+both directions. The domain name should also be the same for collabora server and for the browser which access to the
+online editor.
+
+### Using ngrok (or other http tunnel)
+
+One can configure a tunnel server to expose your local installation to the web and access to your local server using the
+tunnel url.
+
+##### Start ngrok
+
+This can be achieved using [ngrok ](https://ngrok.com/).
+
+   The configuration of ngrok is outside the scope of this document. Refers to the ngrok's documentation.
+
+   # ensuring that your server is running through http and port 8000
+   ngrok http 8000
+   # then open the link given by the ngrok utility, and you should reach your app
+
+At this step, ensure that you can reach your local app using the ngrok url.
+
+##### Configure Collabora
+
+The collabora server must be executed online and configured to access to your ngrok installation. Ensure that the aliasgroup
+exists for your ngrok application ([See the CODE documentation: ](https://sdk.collaboraonline.com/docs/installation/Configuration.html#multihost-configuration)).
+
+##### Configure your app
+
+Set the [EDITOR_SERVER` variable to point to your collabora server, this should be done in your `.env.local` file.
+
+At this point, everything must be fine. In case of errors, watch the log from your collabora server, use the `profiler ](https://symfony.com/doc/current/profiler.html)
+to debug the requests.
+
+   In case of error while validating proof (you'll see those messages in the collabora's logs), you can temporarily disable
+   the proof validation adding this code snippet in `config/services.yaml`:
+
+```yaml
+      when@dev:
+          # add only in the dev environment to avoid security problems
+          services:
+              ChampsLibres\WopiLib\Contract\Service\ProofValidatorInterface:
+                  # this class will always validate proof
+                  alias: Chill\WopiBundle\Service\Wopi\NullProofValidator
+```
+
+### With a local CODE image
+
+   This configuration is not sure and must be refined. The documentation does not seem entirely valid.
+
+##### Use a local domain name and https for your app
+
+Use the proxy feature from the embedded symfony server to run your app. `See the dedicated doc <https://symfony.com/doc/current/setup/symfony_server.html#local-domain-names>[
+
+Configure also the `https certificate ](https://symfony.com/doc/current/setup/symfony_server.html#enabling-tls)
+
+In this example, your local domain name will be `my-domain` and the url will be `https://my-domain.wip`.
+
+Ensure that the proxy is running.
+
+##### Create a certificate database for collabora
+
+Collabora must validate your certificate generated by the symfony console. For that, you need `to create a NSS database <https://sdk.collaboraonline.com/docs/installation/Configuration.html#validating-digital-signatures>`
+and configure collabora to use it.
+
+At first, export the certificate for symfony development. Use the graphical interface from your browser to get the
+certificate as a PEM file.
+
+   # create your database in a custom directory
+   `mkdir /path/to/your/directory`
+   `certutil -N -d /path/to/your/directory`
+   `cat /path/to/your/ca.crt | certutil -d . -A symfony -t -t C,P,C,u,w -a`
+
+Launch CODE properly configured
+
+```yaml
+     collabora:
+         image: collabora/code:latest
+         environment:
+             - SLEEPFORDEBUGGER=0
+             - DONT_GEN_SSL_CERT="True"
+             # add a path to the database
+             - extra_params=--o:ssl.enable=false --o:ssl.termination=false --o:logging.level=7 -o:certificates.database_path=/etc/custom-certificates/nss-database
+             - username=admin
+             - password=admin
+             - dictionaries=en_US
+             - aliasgroup1=https://my-domain.wip
+         ports:
+             - "127.0.0.1:9980:9980"
+         volumes:
+             - "/path/to/your/directory/nss-database:/etc/custom-certificates/nss-database"
+         extra_hosts:
+             - "my-domain.wip:host-gateway"
+```
+
+##### Configure your app
+
+In your `.env.local` file:
+
+   `EDITOR_SERVER=http://${COLLABORA_HOST}:${COLLABORA_PORT}`
+
+At this step, you should be able to edit a document through collabora.

docs/source/installation/enable-collabora-for-dev.rst

@@ -1,125 +0,0 @@
-
-Enable CODE for development
-===========================
-
-For editing a document, there must be a way to communicate between the collabora server and the symfony server, in
-both direction. The domain name should also be the same for collabora server and for the browser which access to the
-online editor.
-
-Using ngrok (or other http tunnel)
-----------------------------------
-
-One can configure a tunnel server to expose your local install to the web, and access to your local server using the
-tunnel url.
-
-Start ngrok
-^^^^^^^^^^^
-
-This can be achieve using `ngrok <https://ngrok.com/>`_.
-
-.. note::
-
-   The configuration of ngrok is outside of the scope of this document. Refers to the ngrok's documentation.
-
-.. code-block:: bash
-
-   # ensuring that your server is running through http and port 8000
-   ngrok http 8000
-   # then open the link given by the ngrok utility and you should reach your app
-
-At this step, ensure that you can reach your local app using the ngrok url.
-
-Configure Collabora
-^^^^^^^^^^^^^^^^^^^
-
-The collabora server must be executed online and configure to access to your ngrok installation. Ensure that the aliasgroup
-exists for your ngrok application (`See the CODE documentation: <https://sdk.collaboraonline.com/docs/installation/Configuration.html#multihost-configuration>`_).
-
-Configure your app
-^^^^^^^^^^^^^^^^^^
-
-Set the :code:`EDITOR_SERVER` variable to point to your collabora server, this should be done in your :code:`.env.local` file.
-
-At this point, everything must be fine. In case of errors, watch the log from your collabora server, use the `profiler <https://symfony.com/doc/current/profiler.html>`_
-to debug the requests.
-
-.. note::
-
-   In case of error while validating proof (you'll see those message in the collabora's logs), you can temporarily disable
-   the proof validation adding this code snippet in `config/services.yaml`:
-
-   .. code-block:: yaml
-
-      when@dev:
-          # add only in dev environment, to avoid security problems
-          services:
-              ChampsLibres\WopiLib\Contract\Service\ProofValidatorInterface:
-                  # this class will always validate proof
-                  alias: Chill\WopiBundle\Service\Wopi\NullProofValidator
-
-With a local CODE image
------------------------
-
-.. warning::
-
-   This configuration is not sure, and must be refined. The documentation does not seems to be entirely valid.
-
-Use a local domain name and https for your app
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Use the proxy feature from embedded symfony server to run your app. `See the dedicated doc <https://symfony.com/doc/current/setup/symfony_server.html#local-domain-names>`
-
-Configure also the `https certificate <https://symfony.com/doc/current/setup/symfony_server.html#enabling-tls>`_
-
-In this example, your local domain name will be :code:`my-domain` and the url will be :code:`https://my-domain.wip`.
-
-Ensure that the proxy is running.
-
-Create a certificate database for collabora
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Collabora must validate your certificate generated by symfony console. For that, you need `to create a NSS database <https://sdk.collaboraonline.com/docs/installation/Configuration.html#validating-digital-signatures>`
-and configure collabora to use it.
-
-At first, export the certificate for symfony development. Use the graphical interface from your browser to get the
-certificate as a PEM file.
-
-.. code-block:: bash
-
-   # create your database in a custom directory
-   mkdir /path/to/your/directory
-   certutil -N -d /path/to/your/directory
-   cat /path/to/your/ca.crt | certutil -d . -A symfony -t -t C,P,C,u,w -a
-
-Launch CODE properly configured
-
-.. code-block:: yaml
-
-     collabora:
-         image: collabora/code:latest
-         environment:
-             - SLEEPFORDEBUGGER=0
-             - DONT_GEN_SSL_CERT="True"
-             # add path to the database
-             - extra_params=--o:ssl.enable=false --o:ssl.termination=false --o:logging.level=7 -o:certificates.database_path=/etc/custom-certificates/nss-database
-             - username=admin
-             - password=admin
-             - dictionaries=en_US
-             - aliasgroup1=https://my-domain.wip
-         ports:
-             - "127.0.0.1:9980:9980"
-         volumes:
-             - "/path/to/your/directory/nss-database:/etc/custom-certificates/nss-database"
-         extra_hosts:
-             - "my-domain.wip:host-gateway"
-
-Configure your app
-^^^^^^^^^^^^^^^^^^
-
-Into your :code:`.env.local` file:
-
-.. code-block:: env
-
-   EDITOR_SERVER=http://${COLLABORA_HOST}:${COLLABORA_PORT}
-
-At this step, you should be able to edit a document through collabora.

docs/source/installation/index.md

@@ -0,0 +1,43 @@
+# Installation & Usage
+
+You will learn here how to install a new symfony project with chill, and configure it.
+
+## Which kind of installation do I need?
+
+### I want to run chill in production
+
+See the [instructions about installing Chill for production ](installation-production.md).
+
+### I want to add features to the main chill bundles
+
+If you want to add features to chill bundles itself, **and** you want those features to be merged into the chill bundles,
+you can use the "development" installation mode.
+
+See the [instruction for installation for development ](installation-for-dev.md).
+
+### I want to add features to Chill, but keep those features for my instance
+
+Follow the same instruction than for production, until the end.
+
+## Requirements
+
+The installation is tested on a Debian-like linux distribution. The installation on other operating systems is not documented.
+
+You have to install the following tools on your computer:
+
+- [PHP](https://www.php.net/): version 8.3+, with the following extensions: pdo_pgsql, intl, mbstring, zip, bcmath, exif, sockets, redis, ast, gd;
+- [composer ](https://getcomposer.org/);
+- [symfony cli ](https://symfony.com/download);
+- [node, we encourage you to use nvm to configure the correct version ](https://github.com/nvm-sh/nvm): The project contains a
+  `nvmrc` file which selects automatically the required version of node (if present).
+- [yarn](https://classic.yarnpkg.com/lang/en/docs/install/): We use version 1.22+ for now.
+- [docker and the plugin compose ](https://docker.com) to run the database
+
+Chill needs a redis server and a postgresql database, and a few other things like a "relatorio service" which will
+generate documents from templates. **All these things are available through docker using the plugin compose**. We do not provide
+information on how to run this without docker compose.
+
+## Instructions
+
+- [Installation for Development](installation-development.md)
+- [Installation for Production](installation-production.md)

docs/source/installation/index.rst

@@ -1,67 +0,0 @@
-.. chill-doc documentation master file, created by
-   sphinx-quickstart on Sun Sep 28 22:04:08 2014.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
-.. Copyright (C)  2014-2019 Champs Libres Cooperative SCRLFS
-   Permission is granted to copy, distribute and/or modify this document
-   under the terms of the GNU Free Documentation License, Version 1.3
-   or any later version published by the Free Software Foundation;
-   with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
-   A copy of the license is included in the section entitled "GNU
-   Free Documentation License".
-
-Installation & Usage
-####################
-
-
-You will learn here how to install a new symfony project with chill, and configure it.
-
-Which can of installation do I need ?
-=====================================
-
-I want to run chill in production
----------------------------------
-
-See the :ref:`instructions about installing Chill for production <installation-production>`.
-
-I want to add features to the main chill bundles
-------------------------------------------------
-
-If you want to add features to chill bundles itself, **and** you want those features to be merged into the chill bundles,
-you can use the "development" installation mode.
-
-See the :ref:`instruction for installation for development <installation-for-dev>`.
-
-I want to add features to Chill, but keep those features for my instance
--------------------------------------------------------------------------
-
-Follow the same instruction than for production, until the end.
-
-Requirements
-============
-
-The installation is tested on a Debian-like linux distribution. The installation on other operating systems is not documented.
-
-You have to install the following tools on your computer:
-
-- `PHP <https://www.php.net/>`_, version 8.3+, with the following extensions: pdo_pgsql, intl, mbstring, zip, bcmath, exif, sockets, redis, ast, gd;
-- `composer <https://getcomposer.org/>`_;
-- `symfony cli <https://symfony.com/download>`_;
-- `node, we encourage you to use nvm to configure the correct version <https://github.com/nvm-sh/nvm>`_. The project contains an
-  :code:`.nvmrc` file which selects automatically the required version of node (if present).
-- `yarn <https://classic.yarnpkg.com/lang/en/docs/install/>`_. We use the version 1.22+ for now.
-- `docker and the plugin compose <https://docker.com>`_ to run the database
-
-Chill needs a redis server and a postgresql database, and a few other things like a "relatorio service" which will
-generate documents from templates. **All these things are available through docker using the plugin compose**. We do not provide
-information on how to run this without docker compose.
-
-Instructions
-============
-
-.. toctree::
-   :maxdepth: 2
-
-   installation-development.rst
-   installation-production.rst

docs/source/installation/installation-development.md

@@ -0,0 +1,77 @@
+## Installation for development or testing purpose only
+
+⚠️ Use this method for development only. ⚠️
+
+You will need:
+
+- [Composer ](https://getcomposer.org)_;
+- [Symfony-cli tool ](https://symfony.com/download)_;
+- [docker ](https://docs.docker.com/engine/install/)_ and
+  [docker-compose ](https://docs.docker.com/compose/)_
+- node > 20 and yarn 1.22
+
+### First initialization
+
+1. clone the repository and move to the cloned directory:
+
+   git clone https://gitlab.com/Chill-Projet/chill-bundles.git
+   cd chill-bundles
+
+2. install dependencies using composer
+
+   composer install
+
+3. Install and compile assets:
+
+   yarn install
+   yarn run encore production
+
+**note** double-check that you have the node version > 20 using the
+``node --version`` command.
+
+1. configure your project: create a ``.env.local`` file at the root, and
+   add the admin password:
+
+   # for this installation mode, the environment should always be "dev"
+   APP_ENV=dev
+   ADMIN_PASSWORD=\$2y\$13\$iyvJLuT4YEa6iWXyQV4/N.hNHpNG8kXlYDkkt5MkYy4FXcSwYAwmm
+   # note: if you copy-paste the line above, the password will be "admin".
+
+2. start the stack using ``docker compose up -d``, check the status of
+   the start with ``docker compose ps``
+
+3. configure all the necessary third-party tools
+
+`     # the first start, it may last some seconds, you can check with docker compose ps
+      # run migrations
+      symfony console doctrine:migrations:migrate
+      # setup messenger
+      symfony console messenger:setup-transports
+      # prepare some views
+      symfony console chill:db:sync-views
+      # generate jwt token, required for some api features (webdav access, ...)
+      symfony console lexik:jwt:generate-keypair`
+
+4. add some fixtures
+
+This will truncate all the existing data of the database. But remember,
+we are in dev mode!
+
+   symfony console doctrine:fixtures:load
+
+5. launch symfony dev-server
+
+   `symfony server:start -d`
+
+And visit the web page it suggests. You can log in with user
+`center a_social` and password `password`, or login `admin` with
+the password you set.
+
+### Stopping the server
+
+   `symfony server:stop`
+
+### Restart the webserver for a later start
+
+   `symfony server:start -d`
+   # this will automatically start the full docker compose services

docs/source/installation/installation-development.rst

@@ -1,101 +0,0 @@
-.. _installation-for-dev:
-
-Installation for development or testing purpose only
-====================================================
-
-⚠️ Use this method for development only. ⚠️
-
-You will need:
-
-- `Composer <https://getcomposer.org>`__;
-- `Symfony-cli tool <https://symfony.com/download>`__;
-- `docker <https://docs.docker.com/engine/install/>`__ and
-  `docker-compose <https://docs.docker.com/compose/>`__
-- node > 20 and yarn 1.22
-
-First initialization
---------------------
-
-1. clone the repository and move to the cloned directory:
-
-.. code:: bash
-
-   git clone https://gitlab.com/Chill-Projet/chill-bundles.git
-   cd chill-bundles
-
-2. install dependencies using composer
-
-.. code:: bash
-
-   composer install
-
-3. Install and compile assets:
-
-.. code:: bash
-
-   yarn install
-   yarn run encore production
-
-**note** double check that you have the node version > 20 using the
-``node --version`` command.
-
-4. configure your project: create a ``.env.local`` file at the root, and
-   add the admin password:
-
-.. code:: dotenv
-
-   # for this installation mode, the environment should always be "dev"
-   APP_ENV=dev
-   ADMIN_PASSWORD=\$2y\$13\$iyvJLuT4YEa6iWXyQV4/N.hNHpNG8kXlYDkkt5MkYy4FXcSwYAwmm
-   # note: if you copy-paste the line above, the password will be "admin".
-
-5. start the stack using ``docker compose up -d``, check the status of
-   the start with ``docker compose ps``
-
-6. configure all the needed third-party tools
-
-   .. code:: bash
-
-      # the first start, it may last some seconds, you can check with docker compose ps
-      # run migrations
-      symfony console doctrine:migrations:migrate
-      # setup messenger
-      symfony console messenger:setup-transports
-      # prepare some views
-      symfony console chill:db:sync-views
-      # generate jwt token, required for some api features (webdav access, ...)
-      symfony console lexik:jwt:generate-keypair
-
-7. add some fixtures
-
-This will truncate all the existing data of the database. But remember,
-we are in dev mode !
-
-.. code:: bash
-
-   symfony console doctrine:fixtures:load
-
-8. launch symfony dev-server
-
-.. code:: bash
-
-   symfony server:start -d
-
-And visit the web page it suggest. You can login with user
-``center a_social`` and password ``password``, or login ``admin`` with
-the password you set.
-
-Stopping the server
--------------------
-
-.. code:: bash
-
-   symfony server:stop
-
-Restart the webserver for subsequent start
-------------------------------------------
-
-.. code:: bash
-
-   symfony server:start -d
-   # this will automatically starts the full docker compose services

docs/source/installation/installation-production.md

@@ -0,0 +1,287 @@
+# Install Chill for production with or without adding personal features
+
+Chill is a set of "bundles" for a symfony app.
+
+To run Chill in production or add new features to it (without merging those features to the chill core), you must create
+a symfony app, and eventually add those features into your app.
+
+Once you are happy with the configuration, [you should follow the dedicated instructions of how to go into production for
+Symfony apps ](https://symfony.com/doc/current/deployment.html).
+
+## Install a new app
+
+### Install required dependencies:
+
+- `jq`: https://jqlang.org/ (install it through your package manager);
+- `php`, minimal version: 8.3;
+- `composer`: https://getcomposer.org/download/
+- `symfony-cli`: https://symfony.com/download
+- `docker` with the plugin `compose`: https://docs.docker.com/engine/install/ and https://docs.docker.com/compose/install/
+
+### Initialize the project and it's dependencies
+
+   symfony new --version=5.4 my_chill_project
+   cd my_chill_project
+
+We strongly encourage you to initialize a git repository at this step, to track further changes.
+
+   # add the flex endpoints required for custom recipes
+   `cat <<< "$(jq '.extra.symfony += {"endpoint": ["flex://defaults", "https://gitlab.com/api/v4/projects/57371968/repository/files/index.json/raw?ref=main"]}' composer.json)" > composer.json`
+   # install chill and some dependencies
+   `symfony composer require -W chill-project/chill-bundles ^3.7.1 champs-libres/wopi-lib dev-master@dev champs-libres/wopi-bundle dev-master@dev symfony/amqp-messenger`
+
+We encourage you to accept the inclusion of the "Docker configuration from recipes": this is the documented way to run the database.
+You must also accept to configure recipes from the contrib repository, unless you want to configure the bundles manually).
+
+`   # fix some configuration
+   ./post-install-chill.sh
+   # populate the cache for the first time. This is necessary to dump some translation files, required for the asset compilation
+   symfony console cache:clear
+   # install node dependencies
+   yarn install
+   # and compile assets
+   yarn run encore production`
+
+   If you encounter this error during asset compilation ([yarn run encore production`) (repeated multiple times):
+
+   ```bash
+      [tsl] ERROR in /tmp/chill/v1/public/bundles/chillcalendar/types.ts(2,65)
+            TS2307: Cannot find module '../../../ChillMainBundle/Resources/public/types' or its corresponding type declarations.
+```
+
+   run:
+
+   ```bash
+      rm -rf public/bundles/*
+```
+
+   Then restart the compilation of assets (```yarn run encore production```)
+
+### Configure your project
+
+You should read the configuration files in `chill/config/packages` carefully, especially if you have
+custom developments. But most of the time, this should be fine.
+
+You have to configure some local variables, which are described in the `.env` file. The secrets should not be stored
+in this `.env` file, but instead using the `secrets management tool ](https://symfony.com/doc/current/configuration/secrets.html)
+or in the `.env.local` file, which should not be committed to the git repository.
+
+You do not need to set variables for the smtp server, redis server and relatorio server, as they are generated automatically
+by the symfony server, from the docker compose services.
+
+The required variables are:
+
+- the `ADMIN_PASSWORD`;
+- the `OVHCLOUD_DSN` variable;
+
+##### `ADMIN_PASSWORD`
+
+You can generate a hashed and salted admin password using the command: `symfony console security:hash-password <your password> 'Symfony\Component\Security\Core\User\User'[.Then,
+you can either:
+
+- add this password to the `.env.local` file, you must escape the character `$`: if the generated password
+  is `$2y$13$iyvJLuT4YEa6iWXyQV4/N.hNHpNG8kXlYDkkt5MkYy4FXcSwYAwmm`, your `.env.local` file will be:
+
+  ```bash
+     ADMIN_PASSWORD=\$2y\$13\$iyvJLuT4YEa6iWXyQV4/N.hNHpNG8kXlYDkkt5MkYy4FXcSwYAwmm
+     # note: if you copy-paste the line above, the password will be "admin".
+  ```
+
+- add the generated password to the secrets manager (**note**: you must add the generated hashed password to the secrets env,
+  not the password in clear text).
+
+##### `OVHCLOUD_DSN` and sending SMS messages
+
+This is a temporary dependency, for ensuring compatibility for previous behaviour.
+
+You can set it to `null://null` if you do not plan to use sending SMS.
+
+   OVHCLOUD_DSN=null://null
+
+If you plan to do it, you can configure the notifier component `as described in the symfony documentation ](https://symfony.com/doc/current/notifier.html#notifier-sms-channel).
+
+Some environment variables are available for the JWT authentication bundle in the [.env` file.
+
+### Prepare database, messenger queue, and other configuration
+
+To continue the installation process, you will have to run migrations:
+
+   # start databases and other services
+   docker compose up -d
+   # the first start, it may last some seconds, you can check with docker compose ps
+   # run migrations
+   symfony console doctrine:migrations:migrate
+   # setup messenger
+   symfony console messenger:setup-transports
+   # prepare some views
+   symfony console chill:db:sync-views
+   # load languages data
+   symfony console chill:main:languages:populate
+   # generate jwt token, required for some api features (webdav access, ...)
+   symfony console lexik:jwt:generate-keypair
+
+   If you encounter this error:
+
+   ```
+   No transport supports the given Messenger DSN.
+   ```
+
+   Please check that you installed the package `symfony/amqp-messenger`.
+
+### Start your web server locally
+
+At this step, Chill will be ready to be served locally, but without any configuration. You can run the project
+locally using the `local symfony server ](https://symfony.com/doc/current/setup/symfony_server.html):
+
+   # see the whole possibilities at https://symfony.com/doc/current/setup/symfony_server.html
+   symfony server:start -d
+
+If you need to test the instance with accounts and some basic configuration, please install the fixtures (see below).
+
+## Add capabilities for dev
+
+If you need to add custom bundles, you can develop them in the [src/` directory, like for any other symfony project. You
+can rely on the whole chill framework, meaning there is no need to add them to the original `chill-bundles`.
+
+You will require some bundles to have the following development tools:
+
+- add fixtures
+- add profiler and debug bundle
+
+### Install fixtures
+
+   # generate fixtures for chill
+   symfony composer require --dev doctrine/doctrine-fixtures-bundle nelmio/alice
+   # now, you can generate fixtures (this will reset your database)
+   symfony console doctrine:fixtures:load
+
+This will generate user accounts, centers, and some basic configuration.
+
+The accounts created are: `center a_social`, `center b_social`, `center a_direction`, ...  The full list is
+visible in the "users" table: `docker compose exec database psql -U app -c "SELECT username FROM users"`.
+
+The password is always `password`.
+
+   The fixtures are not fully functional. See the `corresponding issue ](https://gitlab.com/Chill-Projet/chill-bundles/-/issues/280).
+
+### Add web profiler and debugger
+
+   symfony composer require --dev symfony/web-profiler-bundle symfony/debug-bundle
+
+### Working on chill bundles
+
+If you plan to improve the chill-bundles repository, that's great!
+
+It would be better [to follow the instruction about development ](installation-for-dev.md). But if those features are
+deeply linked to some dev you made in the app, it can be easier to develop within the [vendor/` directory.
+
+You will have to download chill-bundles as a git repository (and not as an archive, which is barely editable).
+
+In your `composer.json` file, add these lines:
+
+    {
+        "config": {
+   +        "preferred-install": {
+   +            "chill-project/chill-bundles": "source",
+                "*": "dist"
+   +         }
+        }
+
+Then, run `symfony composer reinstall chill-project/chill-bundles` to re-install the package from source.
+
+## Update
+
+In order to update your app, you must update dependencies:
+
+- for chill-bundles, you can `set the last version ](https://gitlab.com/Chill-Projet/chill-bundles/-/releases) manually
+  in the [composer.json` file, or set the version to `^3.0.0` and run `symfony composer update` regularly
+- run `composer update` and `yarn update` to maintain your dependencies up-to-date.
+
+After each update, you must update your database schema:
+
+   symfony console doctrine:migrations:migrate
+   symfony console chill:db:sync-views
+
+## Commit and share your project
+
+If multiple developers work on a project, you can commit your symfony project and share it with other people.
+
+When another developer clones your project, they will have to:
+
+- run `symfony composer install` and `yarn install` to install the same dependencies as the initial developer;
+- run `yarn run encore production` to compile assets;
+- copy any possible variables from the `.env.local` files;
+- start the docker compose stack, using `docker compose`, and run migrations, set up transports, and prepare chill db views
+  (see the corresponding command above)
+
+## Operations
+
+### Build assets
+
+run those commands:
+
+`   # for production (or in dev, when you don't need to work on your assets and need some speed)
+   yarn run encore production
+   # in dev, when you want to reload the assets on each changes
+   yarn run encore dev --watch`
+
+### How to execute the console ?
+
+`   # start the console with all required variables
+   symfony console
+   # you can add your command after that:
+   symfony console list`
+
+### How to generate documents
+
+Documents are generated asynchronously by `"consuming messages" ](https://symfony.com/doc/current/messenger.html#consuming-messages-running-the-worker).
+
+You must generate them using a dedicated process:
+
+   symfony console messenger:consume async priority
+
+To avoid memory issues, we encourage you to also use the `--limit` parameter of the command.
+
+### How to read emails sent by the program ?
+
+In development, there is a built-in "mail catcher". Open it with `symfony open:local:webmail`
+
+### How to run cron-jobs ?
+
+Some commands must be executed in [cron jobs ](cronjob.md). To execute them:
+
+   `symfony console chill:cron-job:execute`
+
+### What about materialized views ?
+
+There are some materialized views in chill, to speed up some complex computations in the database.
+
+In order to refresh them, run a cron job or refresh them manually in your database.
+
+## Troubleshooting
+
+### Error `An exception has been thrown during the rendering of a template ("Asset manifest file "/var/www/app/web/build/manifest.json" does not exist.").` on first run
+
+Build assets, see above.
+
+## Go to production
+
+Currently, to run this software in production, the *state of the art* is the following :
+
+1. Run the software locally and tweak the configuration to your needs ;
+2. Build the image and store it in a private container registry.
+
+   In production, you **must** set these variables:
+
+   * ``APP_ENV`` to ``prod``
+   * ``APP_DEBUG`` to ``false``
+
+   There are security issues if you keep the same variables as for production.
+
+## Going further
+
+- [Production Setup](prod.md)
+- [Document Storage](document-storage.md)
+- [Load Addresses](load-addresses.md)
+- [Production Calendar SMS Sending](prod-calendar-sms-sending.md)
+- [Microsoft Graph Configuration](msgraph-configure.md)

docs/source/installation/installation-production.rst

@@ -1,365 +0,0 @@
-.. _installation-production:
-
-Install Chill for production with or without adding personal features
-#####################################################################
-
-Chill is a set of "bundles" for a symfony app.
-
-To run Chill in production or add new features to it (without merging those features to the chill core), you must create
-a symfony app, and eventually add those features into your app.
-
-Once you are happy with the configuration, `you should follow the dedicated instructions of how to go into production for
-Symfony apps <https://symfony.com/doc/current/deployment.html>`_.
-
-Install a new app
-=================
-
-Install required dependencies:
-------------------------------
-
-- `jq`: https://jqlang.org/ (install it through your package manager);
-- `php`, minimal version: 8.3;
-- `composer`: https://getcomposer.org/download/
-- `symfony-cli`: https://symfony.com/download
-- `docker` with the plugin `compose`: https://docs.docker.com/engine/install/ and https://docs.docker.com/compose/install/
-
-
-Initialize project and dependencies
------------------------------------
-
-.. code-block:: bash
-
-   symfony new --version=5.4 my_chill_project
-   cd my_chill_project
-
-We strongly encourage you to initialize a git repository at this step, to track further changes.
-
-.. code-block:: bash
-
-   # add the flex endpoints required for custom recipes
-   cat <<< "$(jq '.extra.symfony += {"endpoint": ["flex://defaults", "https://gitlab.com/api/v4/projects/57371968/repository/files/index.json/raw?ref=main"]}' composer.json)" > composer.json
-   # install chill and some dependencies
-   symfony composer require -W chill-project/chill-bundles ^3.7.1 champs-libres/wopi-lib dev-master@dev champs-libres/wopi-bundle dev-master@dev symfony/amqp-messenger
-
-We encourage you to accept the inclusion of the "Docker configuration from recipes": this is the documented way to run the database.
-You must also accept to configure recipes from the contrib repository, unless you want to configure the bundles manually).
-
-.. code-block:: bash
-
-   # fix some configuration
-   ./post-install-chill.sh
-   # populate the cache for the first time. This is necessary to dump some translation files, required for the assets compilation
-   symfony console cache:clear
-   # install node dependencies
-   yarn install
-   # and compile assets
-   yarn run encore production
-
-.. note::
-
-   If you encounter this error during assets compilation (:code:`yarn run encore production`) (repeated multiple times):
-
-   .. code-block::
-
-      [tsl] ERROR in /tmp/chill/v1/public/bundles/chillcalendar/types.ts(2,65)
-            TS2307: Cannot find module '../../../ChillMainBundle/Resources/public/types' or its corresponding type declarations.
-
-   run:
-
-   .. code-block:: bash
-
-      rm -rf public/bundles/*
-
-   Then restart the compilation of assets (:code:```yarn run encore production```)
-
-Configure your project
-----------------------
-
-You should read the configuration files in :code:`chill/config/packages` carefully, especially if you have
-custom developments. But most of the time, this should be fine.
-
-You have to configure some local variables, which are described in the :code:`.env` file. The secrets should not be stored
-in this :code:`.env` file, but instead using the `secrets management tool <https://symfony.com/doc/current/configuration/secrets.html>`_
-or in the :code:`.env.local` file, which should not be committed to the git repository.
-
-You do not need to set variables for the smtp server, redis server and relatorio server, as they are generated automatically
-by the symfony server, from the docker compose services.
-
-The required variables are:
-
-- the :code:`ADMIN_PASSWORD`;
-- the :code:`OVHCLOUD_DSN` variable;
-
-:code:`ADMIN_PASSWORD`
-^^^^^^^^^^^^^^^^^^^^^^
-
-You can generate a hashed and salted admin password using the command
-:code:`symfony console security:hash-password <your password> 'Symfony\Component\Security\Core\User\User'`.Then,
-you can either:
-
-- add this password to the :code:`.env.local` file, you must escape the character :code:`$`: if the generated password
-  is :code:`$2y$13$iyvJLuT4YEa6iWXyQV4/N.hNHpNG8kXlYDkkt5MkYy4FXcSwYAwmm`, your :code:`.env.local` file will be:
-
-  .. code-block:: bash
-
-     ADMIN_PASSWORD=\$2y\$13\$iyvJLuT4YEa6iWXyQV4/N.hNHpNG8kXlYDkkt5MkYy4FXcSwYAwmm
-     # note: if you copy-paste the line above, the password will be "admin".
-
-- add the generated password to the secrets manager (**note**: you must add the generated hashed password to the secrets env,
-  not the password in clear text).
-
-:code:`OVHCLOUD_DSN` and sending SMS messages
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This is a temporary dependency, for ensuring compatibility for previous behaviour.
-
-You can set it to :code:`null://null` if you do not plan to use sending SMS.
-
-.. code-block:: bash
-
-   OVHCLOUD_DSN=null://null
-
-If you plan to do it, you can configure the notifier component `as described in the symfony documentation <https://symfony.com/doc/current/notifier.html#notifier-sms-channel>`_.
-
-
-Some environment variables are available for the JWT authentication bundle in the :code:`.env` file.
-
-Prepare database, messenger queue, and other configuration
-----------------------------------------------------------
-
-To continue the installation process, you will have to run migrations:
-
-.. code-block:: bash
-
-   # start databases and other services
-   docker compose up -d
-   # the first start, it may last some seconds, you can check with docker compose ps
-   # run migrations
-   symfony console doctrine:migrations:migrate
-   # setup messenger
-   symfony console messenger:setup-transports
-   # prepare some views
-   symfony console chill:db:sync-views
-   # load languages data
-   symfony console chill:main:languages:populate
-   # generate jwt token, required for some api features (webdav access, ...)
-   symfony console lexik:jwt:generate-keypair
-
-.. note::
-
-   If you encounter this error:
-
-   .. code-block::
-
-     No transport supports the given Messenger DSN.
-
-   Please check that you installed the package `symfony/amqp-messenger`.
-
-
-
-Start your web server locally
------------------------------
-
-At this step, Chill will be ready to be served locally, but without any configuration. You can run the project
-locally using the `local symfony server <https://symfony.com/doc/current/setup/symfony_server.html>`_:
-
-.. code-block:: bash
-
-   # see the whole possibilities at https://symfony.com/doc/current/setup/symfony_server.html
-   symfony server:start -d
-
-
-If you need to test the instance with accounts and some basic configuration, please install the fixtures (see below).
-
-
-Add capabilities for dev
-========================
-
-If you need to add custom bundles, you can develop them in the `src/` directory, like for any other symfony project. You
-can rely on the whole chill framework, meaning there is no need to add them to the original `chill-bundles`.
-
-You will require some bundles to have the following development tools:
-
-- add fixtures
-- add profiler and debug bundle
-
-Install fixtures
-----------------
-
-.. code-block:: bash
-
-   # generate fixtures for chill
-   symfony composer require --dev doctrine/doctrine-fixtures-bundle nelmio/alice
-   # now, you can generate fixtures (this will reset your database)
-   symfony console doctrine:fixtures:load
-
-This will generate user accounts, centers, and some basic configuration.
-
-The accounts created are: :code:`center a_social`, :code:`center b_social`, :code:`center a_direction`, ...  The full list is
-visible in the "users" table: :code:`docker compose exec database psql -U app -c "SELECT username FROM users"`.
-
-The password is always :code:`password`.
-
-.. warning::
-
-   The fixtures are not fully functional. See the `corresponding issue <https://gitlab.com/Chill-Projet/chill-bundles/-/issues/280>`_.
-
-Add web profiler and debugger
------------------------------
-
-.. code-block:: bash
-
-   symfony composer require --dev symfony/web-profiler-bundle symfony/debug-bundle
-
-Working on chill bundles
-------------------------
-
-If you plan to improve the chill-bundles repository, that's great!
-
-It would be better :ref:`to follow the instruction about development <installation-for-dev>`. But if those features are
-deeply linked to some dev you made in the app, it can be easier to develop within the :code:`vendor/` directory.
-
-You will have to download chill-bundles as a git repository (and not as an archive, which is barely editable).
-
-In your :code:`composer.json` file, add these lines:
-
-.. code-block:: diff
-
-    {
-        "config": {
-   +        "preferred-install": {
-   +            "chill-project/chill-bundles": "source",
-                "*": "dist"
-   +         }
-        }
-
-Then, run :code:`symfony composer reinstall chill-project/chill-bundles` to re-install the package from source.
-
-
-Update
-======
-
-In order to update your app, you must update dependencies:
-
-- for chill-bundles, you can `set the last version <https://gitlab.com/Chill-Projet/chill-bundles/-/releases>`_ manually
-  in the :code:`composer.json` file, or set the version to `^3.0.0` and run :code:`symfony composer update` regularly
-- run :code:`composer update` and :code:`yarn update` to maintain your dependencies up-to-date.
-
-After each update, you must update your database schema:
-
-.. code-block:: bash
-
-   symfony console doctrine:migrations:migrate
-   symfony console chill:db:sync-views
-
-
-Commit and share your project
-=============================
-
-If multiple developers work on a project, you can commit your symfony project and share it with other people.
-
-When another developer clones your project, they will have to:
-
-- run :code:`symfony composer install` and :code:`yarn install` to install the same dependencies as the initial developer;
-- run :code:`yarn run encore production` to compile assets;
-- copy any possible variables from the :code:`.env.local` files;
-- start the docker compose stack, using :code:`docker compose`, and run migrations, set up transports, and prepare chill db views
-  (see the corresponding command above)
-
-Operations
-==========
-
-Build assets
-------------
-
-run those commands:
-
-.. code-block:: bash
-
-   # for production (or in dev, when you don't need to work on your assets and need some speed)
-   yarn run encore production
-   # in dev, when you wan't to reload the assets on each changes
-   yarn run encore dev --watch
-
-How to execute the console ?
-----------------------------
-
-.. code-block:: bash
-
-   # start the console with all required variables
-   symfony console
-   # you can add your command after that:
-   symfony console list
-
-How to generate documents
--------------------------
-
-Documents are generated asynchronously by `"consuming messages" <https://symfony.com/doc/current/messenger.html#consuming-messages-running-the-worker>`_.
-
-You must generate them using a dedicated process:
-
-.. code-block:: bash
-
-   symfony console messenger:consume async priority
-
-To avoid memory issues, we encourage you to also use the :code:`--limit` parameter of the command.
-
-How to read emails sent by the program ?
--------------------------------------------
-
-In development, there is a built-in "mail catcher". Open it with :code:`symfony open:local:webmail`
-
-How to run cron-jobs ?
-----------------------
-
-Some commands must be executed in :ref:`cron jobs <cronjob>`. To execute them:
-
-.. code-block:: bash
-
-   symfony console chill:cron-job:execute
-
-What about materialized views ?
--------------------------------
-
-There are some materialized views in chill, to speed up some complex computations in the database.
-
-In order to refresh them, run a cron job or refresh them manually in your database.
-
-
-Troubleshooting
-===============
-
-Error `An exception has been thrown during the rendering of a template ("Asset manifest file "/var/www/app/web/build/manifest.json" does not exist.").` on first run
---------------------------------------------------------------------------------------------------------------------------------------------------------------------
-
-Build assets, see above.
-
-Go to production
-================
-
-Currently, to run this software in production, the *state of the art* is the following :
-
-1. Run the software locally and tweak the configuration to your needs ;
-2. Build the image and store it in a private container registry.
-
-.. warning::
-
-   In production, you **must** set these variables:
-
-   * ``APP_ENV`` to ``prod``
-   * ``APP_DEBUG`` to ``false``
-
-   There are security issues if you keep the same variables as for production.
-
-
-Going further
-=============
-
-.. toctree::
-   :maxdepth: 2
-
-   prod.rst
-   document-storage.rst
-   load-addresses.rst
-   prod-calendar-sms-sending.rst
-   msgraph-configure.rst

docs/source/installation/load-addresses.md

@@ -0,0 +1,47 @@
+###### Addresses
+
+Chill can store a list of geolocated address references, which are used to suggest address and ensure that the data is correctly stored.
+
+Those addresses may be loaded from a dedicated source.
+
+## Countries
+
+To load addresses into the chill application we first have to make sure that a list of countries is present.
+To import, the countries run the following command.
+
+    bin/console chill:main:countries:populate
+
+## In France
+
+The address is loaded from the [BANO ](https://bano.openstreetmap.fr/). The postal codes are loaded from [the official list of
+postal codes ](https://datanova.laposte.fr/explore/dataset/laposte_hexasmal/information/)
+
+   # first, load postal codes
+   `bin/console chill:main:postal-code:load:FR`
+   # then, load all addresses by departement (multiple departements can be loaded by repeating the departement code
+   `bin/console chill:main:address-ref-from-bano 57 54 51`
+
+## In Belgium
+
+Addresses are prepared from the [BeST Address data ](https://www.geo.be/catalog/details/ca0fd5c0-8146-11e9-9012-482ae30f98d9).
+
+Postal code is loaded from this database. There is no need to load postal codes from another source (actually, this is strongly discouraged).
+
+The data are prepared for Chill ([See this repository ](https://gitea.champs-libres.be/Chill-project/belgian-bestaddresses-transform/releases)).
+One can select postal code by his first number (`1xxx` for postal codes from 1000 to 1999), or a limited list for development purpose.
+
+The command expects a language code as the first argument.
+
+   # load postal code from 1000 to 3999:
+   `bin/console chill:main:address-ref-from-best-addresse fr 1xxx 2xxx 3xxx`
+
+   # load only an extract (for dev purposes)
+   `bin/console chill:main:address-ref-from-best-addresse fr extract`
+
+   # load full addresses (discouraged)
+   `bin/console chill:main:address-ref-from-best-addresse fr full`
+
+   There is a possibility to load the full list of addresses is discouraged: the loading is optimized with smaller extracts.
+
+   Once you load the full list, it is not possible to load a smaller extract: each extract loaded **after** will not
+   delete the addresses loaded with the full extract (and some addresses will be present twice).

docs/source/installation/load-addresses.rst

@@ -1,62 +0,0 @@
-
-.. _addresses:
-
-Addresses
-*********
-
-Chill can store a list of geolocated address references, which are used to suggest address and ensure that the data is correctly stored.
-
-Those addresses may be load from a dedicated source.
-
-Countries
-=========
-
-In order to load addresses into the chill application we first have to make sure that a list of countries is present.
-To import the countries run the following command.
-
-.. code-block:: bash
-
-    bin/console chill:main:countries:populate
-
-In France
-=========
-
-The address are loaded from the `BANO <https://bano.openstreetmap.fr/>`_. The postal codes are loaded from `the official list of
-postal codes <https://datanova.laposte.fr/explore/dataset/laposte_hexasmal/information/>`_
-
-.. code-block:: bash
-
-   # first, load postal codes
-   bin/console chill:main:postal-code:load:FR
-   # then, load all addresses, by departement (multiple departement can be loaded by repeating the departement code
-   bin/console chill:main:address-ref-from-bano 57 54 51
-
-In Belgium
-==========
-
-Addresses are prepared from the `BeST Address data <https://www.geo.be/catalog/details/ca0fd5c0-8146-11e9-9012-482ae30f98d9>`_.
-
-Postal code are loaded from this database. There is no need to load postal codes from another source (actually, this is strongly discouraged).
-
-The data are prepared for Chill (`See this repository <https://gitea.champs-libres.be/Chill-project/belgian-bestaddresses-transform/releases>`_).
-One can select postal code by his first number (:code:`1xxx` for postal codes from 1000 to 1999), or a limited list for development purpose.
-
-The command expects a language code as first argument.
-
-.. code-block:: bash
-
-   # load postal code from 1000 to 3999:
-   bin/console chill:main:address-ref-from-best-addresse fr 1xxx 2xxx 3xxx
-
-   # load only an extract (for dev purposes)
-   bin/console chill:main:address-ref-from-best-addresse fr extract
-
-   # load full addresses (discouraged)
-   bin/console chill:main:address-ref-from-best-addresse fr full
-
-.. note::
-
-   There is a possibility to load the full list of addresses is discouraged: the loading is optimized with smaller extracts.
-
-   Once you load the full list, it is not possible to load smaller extract: each extract loaded **after** will not
-   delete the addresses loaded with the full extract (and some addresses will be present twice).

docs/source/installation/msgraph-configure.md

@@ -1,70 +1,53 @@
-
-Configure Chill for calendar and absence synchronisation and SSO with Microsoft Graph (Outlook)
-===============================================================================================
+## Configure Chill for calendar and absence synchronisation and SSO with Microsoft Graph (Outlook)
 
 Chill offers the possibility to:
 
 * authenticate users using Microsoft Graph, with relatively small adaptations;
-* synchronize calendar in both ways (`see the user manual for a large description of the feature <https://gitea.champs-libres.be/Chill-project/manuals>`_).
+* synchronize calendar in both ways ([see the user manual for a large description of the feature ](https://gitea.champs-libres.be/Chill-project/manuals)).
 
-Both can be configured separately (synchronising calendars without SSO, or SSO without calendar).
+Both can be configured separately (synchronising calendars without SSO, or SSO without a calendar).
 
 Please note that the user's email address is the key to associate Chill's users with Microsoft's ones.
 
-Configure SSO
--------------
+### Configure SSO
 
-On Azure side
-*************
+###### On the Azure side
 
-Configure an app with the Azure interface, and give it the name of your choice.
+Configure an app with the Azure interface and give it the name of your choice.
 
 Grab the tenant's ID for your app, which is visible on the main tab "Vue d'ensemble":
 
-.. figure:: ./saml_login_id_general.png
+This is the variable which will be named `SAML_IDP_APP_UUID`.
 
-This the variable which will be named :code:`SAML_IDP_APP_UUID`.
+Go to the "Single sign-on" ("Authentication unique") section. Choose "SAML" as a protocol and fill those values:
 
-Go to the "Single sign-on" ("Authentication unique") section. Choose "SAML" as protocol, and fill those values:
+1. The `entityId` seems to be arbitrary. This will be your variable `SAML_ENTITY_ID`;
+2. The url response must be your Chill's URL appended by `/saml/acs`
+3. The only used attributes is `emailaddress`, which must match the user's email one.
 
-.. figure:: ./saml_login_1.png
+You must download the certificate, as base64. The format for the download is `cer`: you will remove the first and last line (the ones with `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----`), and remove all the return line. The final result should be something as `MIIAbcdef...XyZA=`.
 
-1. The :code:`entityId` seems to be arbitrary. This will be your variable :code:`SAML_ENTITY_ID`;
-2. The url response must be your Chill's URL appended by :code:`/saml/acs`
-3. The only used attributes is :code:`emailaddress`, which must match the user's email one.
-
-.. figure:: ./saml_login_2.png
-
-You must download the certificate, as base64. The format for the download is :code:`cer`: you will remove the first and last line (the ones with :code:`-----BEGIN CERTIFICATE-----` and :code:`-----END CERTIFICATE-----`), and remove all the return line. The final result should be something as :code:`MIIAbcdef...XyZA=`.
-
-This certificat will be your :code:`SAML_IDP_X509_CERT` variable.
+This certificat will be your `SAML_IDP_X509_CERT` variable.
 
 The url login will be filled automatically with your tenant id.
 
-Do not forget to provider user's accesses to your app, using the "Utilisateurs et groupes" tab:
+Remember to provider user's access to your app, using the "Utilisateurs et groupes" tab:
 
-.. figure:: ./saml_login_appro.png
-
-
-You must know have gathered all the required variables for SSO:
-
-.. code-block::
+You must now have gathered all the required variables for SSO:
 
    SAML_BASE_URL=https://test.chill.be # must be
    SAML_ENTITY_ID=https://test.chill.be # must match the one entered
    SAML_IDP_APP_UUID=42XXXXXX-xxxx-xxxx-xxxx-xxxxxxxxxxxx
    SAML_IDP_X509_CERT: MIIC...E8u3bk # truncated
 
-Configure chill app
-*******************
+###### Configure chill app
 
-* add the bundle :code:`hslavich/oneloginsaml-bundle`
+* add the bundle `hslavich/oneloginsaml-bundle`
 * add the configuration file (see example above)
 * configure the security part (see example above)
 * add a user SAML factory into your src, and register it
 
-
-.. code-block:: yaml
+```yaml
 
    # config/packages/hslavich_onelogin.yaml
 
@@ -74,7 +57,6 @@ Configure chill app
      saml_idp_x509cert: '%env(resolve:SAML_IDP_X509_CERT)%'
      saml_idp_app_uuid: '%env(resolve:SAML_IDP_APP_UUID)%'
 
-
    hslavich_onelogin_saml:
      # Basic settings
      idp:
@@ -124,16 +106,14 @@ Configure chill app
          name: 'Example'
          displayname: 'Example'
          url: 'http://example.com'
+```
 
-
-.. code-block:: yaml
-
+```yaml
    # config/security.yaml
    # merge this with other existing configurations
 
    security:
 
-
        providers:
            saml_provider:
                # Loads user from user repository
@@ -143,7 +123,6 @@ Configure chill app
 
        firewalls:
 
-
            default:
                # saml part:
                saml:
@@ -158,10 +137,9 @@ Configure chill app
                    login_path: saml_login
                logout:
                    path: /saml/logout
+```
 
-
-.. code-block:: php
-
+```php
    // src/Security/SamlFactory.php
 
    namespace App\Security;
@@ -185,105 +163,87 @@ Configure chill app
            return $user;
        }
    }
+```
 
-
-
-Configure sync and calendar access
-----------------------------------
+### Configure sync and calendar access
 
 The purpose of this configuration is the following:
 
 - let user read their calendar and shared calendar within Chill (with the same permissions as the one configured in Outlook / Azure);
-- allow chill instance to write appointment ("Rendez-vous") into their calendar, and invite other users to their appointment;
-- allow chill instance to be notified if an appoint is added or removed by the user within another interface than Chill: if the appointment match another one created in the Chill interface, the date and time are updated in Chill;
+- allow chill instance to write appointment ("Rendez-vous") into their calendar and invite other users to their appointment;
+- allow chill instance to be notified if an appointment is added or removed by the user within another interface than Chill: if the appointment matches another one created in the Chill interface, the date and time are updated in Chill;
 - allow chill instance to read the absence of the user and, if set, mark the user as absent in Chill;
 
-The sync processe might be configured in the same app, or into a different app on the Azure side.
+The sync process might be configured in the same app, or into a different app on the Azure side.
 
 The synchronization processes use Oauth 2.0 / OpenID Connect for authentication and authorization.
 
-.. note::
-
    Two flows are in use:
 
-   * we authenticate "on behalf of a user", to allow users to see their own calendar or other user's calendar into the web interface.
+   * we authenticate "on behalf of a user", to allow users to see their own calendar or another user's calendar into the web interface.
 
-     Typically, when the page is loaded, Chill first check that an authorization token exists. If not, the user is redirected to Microsoft Azure for authentification and a new token is grabbed (most of the times, this is transparent for users).
+     Typically, when the page is loaded, Chill first checks that an authorization token exists. If not, the user is redirected to Microsoft Azure for authentification, and a new token is grabbed (most of the times, this is transparent for users).
 
    * Chill also acts "as a machine", to synchronize calendars with a daemon background.
 
 One can access the configuration using this screen (it is quite well hidden into the multiple of tabs):
 
-.. figure:: ./oauth_app_registration.png
+   You can find the oauth configuration on the "Securité > Autorisations" tab and click on "application registration" (not translated).
 
-   You can find the oauth configuration on the "Securité > Autorisations" tab, and click on "application registration" (not translated).
+Add a redirection URI for your authentification:
 
-Add a redirection URI for you authentification:
-
-.. figure:: ./oauth_api_authentification.png
-
-   The URI must be "your chill public url" with :code:`/connect/azure/check` at the end.
+   The URI must be "your chill public url" with `/connect/azure/check` at the end.
 
 Allow some authorizations for your app:
 
-.. figure:: ./oauth_api_autorisees.png
-
-Take care of the separation between autorization "on behalf of a user" (déléguée), or "for a machine" (application).
+Take care of the separation between authorization "on behalf of a user" (déléguée), or "for a machine" (application).
 
 Some explanation:
 
-* Users must be allowed to read their user profile (:code:`User.Read`), and the profile of other users (:code:`User.ReadBasicAll`);
-* They must be allowed to read their calendar (:code:`Calendars.Read`), and the calendars shared with them (:code:`Calendars.Read.Shared`);
+* Users must be allowed to read their user profile (`User.Read`), and the profile of other users (`User.ReadBasicAll`);
+* They must be allowed to read their calendar (`Calendars.Read`), and the calendars shared with them (`Calendars.Read.Shared`);
 
 The sync daemon must have write access:
 
-* the daemon must be allowed to read all users and their profile, to establish a link between them and the Chill's users: (:code:`Users.Read.All`);
-* it must also be allowed to read and write into the calendars (:code:`Calendars.ReadWrite.All`);
-* for sending invitation to other users, the permission (:code:`Mail.Send`) must be granted;
-* and, for reading the absence status of the user and sync it with chill, it must be able to read the mailboxSettings (:code:`MailboxSettings.Read`).
+* the daemon must be allowed to read all users and their profile, to establish a link between them and the Chill's users: (`Users.Read.All`);
+* it must also be allowed to read and write into the calendars (`Calendars.ReadWrite.All`);
+* for sending invitation to other users, the permission (`Mail.Send`) must be granted;
+* and, for reading the absence status of the user and sync it with chill, it must be able to read the mailboxSettings (`MailboxSettings.Read`).
 
-At this step, you might choose to accept those permissions for all users, or let them do it by yourself.
+At this step, you might choose to accept those permissions for all users or let them do it by yourself.
 
 Grab your client id:
 
-.. figure:: ./oauth_api_client_id.png
-
-This will be your :code:`OAUTH_AZURE_CLIENT_ID` variable.
-
+This will be your `OAUTH_AZURE_CLIENT_ID` variable.
 
 Generate a secret:
 
-.. figure:: ./oauth_api_secret.png
+This will be your `OAUTH_AZURE_CLIENT_SECRET` variable.
 
-This will be your :code:`OAUTH_AZURE_CLIENT_SECRET` variable.
-
-And get you azure's tenant id, which is the same as the :code:`SAML_IDP_APP_UUID` (see above).
+And get you azure's tenant id, which is the same as the `SAML_IDP_APP_UUID` (see above).
 
 Your variables will be:
 
-.. code-block::
-
    OAUTH_AZURE_CLIENT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
    OAUTH_AZURE_CLIENT_TENANT=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
    OAUTH_AZURE_CLIENT_SECRET: 3-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
 
 Then, configure chill:
 
-Enable the calendar sync with microsoft azure:
-
-.. code-block:: yaml
+Enable the calendar sync with Microsoft Azure:
 
+```yaml
    # config/packages/chill_calendar.yaml
 
    chill_calendar:
        remote_calendars_sync:
            microsoft_graph:
                enabled: true
+```
 
 and configure the oauth client:
 
-.. code-block:: yaml
-
+```yaml
    # config/packages/knp_oauth2_client.yaml
    knpu_oauth2_client:
        clients:
@@ -296,35 +256,30 @@ and configure the oauth client:
                tenant: '%env(OAUTH_AZURE_CLIENT_TENANT)%'
                url_api: 'https://graph.microsoft.com/'
                default_end_point_version: '2.0'
+```
 
+You can now process for the first api authorization on the application side, (unless you did it in the Azure interface) and get the first token by using :
 
-You can now process for the first api authorization on the application side, (unless you did it in the Azure interface), and get a first token, by using :
+`bin/console chill:calendar:msgraph-grant-admin-consent`
 
-:code:`bin/console chill:calendar:msgraph-grant-admin-consent`
+This will generate an url that you can use to grant your app for your tenant. The redirection may fail in the browser, but this is not relevant: if you get an authorization token in the CLI, the authentication works.
 
-This will generate a url that you can use to grant your app for your tenant. The redirection may fails in the browser, but this is not relevant: if you get an authorization token in the CLI, the authentication works.
+### Run the processes to synchronize
 
-Run the processes to synchronize
---------------------------------
+The calendar synchronization is processed using symfony messenger. It seems to be interesting to configure a queue (in the postgresql database it is the simplest way), and to run a worker for synchronization, at least in production.
 
-The calendar synchronization is processed using symfony messenger. It seems to be intersting to configure a queue (in the postgresql database it is the most simple way), and to run a worker for synchronization, at least in production.
+This cli command does the association between chill's users and Microsoft's users:
 
-The association between chill's users and Microsoft's users is done by this cli command:
-
-.. code-block::
-
-   bin/console chill:calendar:msgraph-user-map-subscribe
+   `bin/console chill:calendar:msgraph-user-map-subscribe`
 
 This command:
 
 * will associate the Microsoft's user metadata in our database;
-* and, most important, create a subscription to get notification when the user alter his calendar, to sync chill's event and ranges in sync.
+* and, most important, create a subscription to get notification when the user alters his calendar, to sync chill's event and ranges in sync.
 
-The subscription least at most 3 days. This command should be runned:
+The subscription is at least at most 3 days. This command should be run:
 
 * at least each time a user is added;
 * and, at least, every three days.
 
-In production, we advise to run it at least every day to get the sync working.
-
-
+In production, we advise running it at least every day to get the sync working.

docs/source/installation/prod-calendar-sms-sending.md

@@ -0,0 +1,21 @@
+## Send short messages (SMS) with the calendar bundle
+
+To activate the sending of messages, you should run this command on a regular basis (using, for instance, a cronjob):
+
+   `bin/console chill:calendar:send-short-messages`
+
+A transporter must be configured for the message to be effectively sent.
+
+### Configure OVH Transporter
+
+Currently, this is the only one transporter available.
+
+To configure this, add this config variable in your environment:
+
+```env
+SHORT_MESSAGE_DSN=ovh://applicationKey:applicationSecret@endpoint?consumerKey=xxxx&sender=yyyy&service_name=zzzz
+```
+
+To generate the application key, secret, and consumerKey, refers to their `documentation ](https://docs.ovh.com/gb/en/api/first-steps-with-ovh-api/).
+
+Before to be able to send your first sms, you must enable your account, grab some credits, and configure a sender. The service_name is an internal configuration generated by OVH.

docs/source/installation/prod-calendar-sms-sending.rst

@@ -1,27 +0,0 @@
-
-Send short messages (SMS) with calendar bundle
-==============================================
-
-To activate the sending of messages, you should run this command on a regularly basis (using, for instance, a cronjob):
-
-.. code-block:: bash
-
-   bin/console chill:calendar:send-short-messages
-
-A transporter must be configured for the message to be effectively sent. 
-
-Configure OVH Transporter
--------------------------
-
-Currently, this is the only one transporter available.
-
-For configuring this, simply add this config variable in your environment:
-
-```env
-SHORT_MESSAGE_DSN=ovh://applicationKey:applicationSecret@endpoint?consumerKey=xxxx&sender=yyyy&service_name=zzzz
-```
-
-In order to generate the application key, secret, and consumerKey, refers to their `documentation <https://docs.ovh.com/gb/en/api/first-steps-with-ovh-api/>`_.
-
-Before to be able to send your first sms, you must enable your account, grab some credits, and configure a sender. The service_name is an internal configuration generated by OVH.
-

docs/source/installation/prod.md

@@ -0,0 +1,62 @@
+Permission is granted to copy, distribute and/or modify this document
+    under the terms of the GNU Free Documentation License, Version 1.3,
+    or any later version published by the Free Software Foundation;
+    with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+    A copy of the license is included in the section entitled "GNU
+    Free Documentation License".
+
+# Installation for production
+
+An installation uses these services, which are deployed using docker containers:
+
+* a php-fpm image, which runs the Php and Symfony code for Chill;
+* a nginx image, which serves the assets and usually proxies the php requests to the fpm image;
+* a redis server, which stores the cache, sessions (this is currently hardcoded in the php image), and some useful keys (like wopi locks);
+* a postgresql database. The use of postgresql is mandatory;
+* a relater service, which transforms odt templates to full documents (replacing the placeholders);
+
+Some external services:
+
+* (required) an openstack object store, configured with `temporary url <https://docs.openstack.org/swift/latest/api/temporary_url_middleware.html>` configured (no openstack users are required). This is currently the only way to store documents from chill;
+* a mailer service (SMTP)
+* (optional) a service for verifying phone number. Currently, only Twilio is possible;
+* (optional) a service for sending Short Messages (SMS). Currently, only Ovh is possible;
+
+The `docker-compose.yaml` file of chill app is a basis for a production install. The environment variable in the ```.env``` and ```.env.prod``` should be overridden by environment variables, or ```.env.local``` files.
+
+This should be adapted to your needs:
+
+* The images for php and nginx apps are pre-compiled images, with the default configuration and bundle. If they do not fullfill your needs, you should compile your own images.
+
+   .. TODO:
+
+      As the time of writing (2022-07-03) those images are not published yet.
+
+* Think about how you will back up your database. Some adminsys find it easier to store a database outside of docker, which might be easier to administrate or replicate.
+
+## Run migrations on each update
+
+Every time you start a new version, you should apply update the sql schema:
+
+- running ``bin/console doctrine:migration:migrate`` to run SQL migration;
+- synchronizing SQL views to the last state: ``bin/console chill:db:sync-views``
+
+## Cron jobs
+
+The command `chill:cron-job:execute` should be executed every 15 minutes (more or less).
+
+This command should never be executed concurrently. It should be not having more than one process for a single instance.
+
+## Post-install tasks
+
+- import addresses. See [addresses](addresses.md).
+
+## Tweak symfony messenger
+
+Calendar sync is processed using symfony messenger.
+
+You can tweak the configuration
+
+Going further:
+
+* Configure the saml login and synchronization with Outlook api

docs/source/installation/prod.rst

@@ -1,71 +0,0 @@
-.. Copyright (C)  2014-2019 Champs Libres Cooperative SCRLFS
-    Permission is granted to copy, distribute and/or modify this document
-    under the terms of the GNU Free Documentation License, Version 1.3
-    or any later version published by the Free Software Foundation;
-    with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
-    A copy of the license is included in the section entitled "GNU
-    Free Documentation License".
-
-.. _prod:
-
-Installation for production
-###########################
-
-An installation use these services, which are deployed using docker containers:
-
-* a php-fpm image, which run the Php and Symfony code for Chill;
-* a nginx image, which serves the assets, and usually proxy the php requests to the fpm image;
-* a redis server, which stores the cache, sessions (this is currently hardcoded in the php image), and some useful keys (like wopi locks);
-* a postgresql database. The use of postgresql is mandatory;
-* a relatorio service, which transform odt templates to full documents (replacing the placeholders);
-
-Some external services:
-
-* (required) an openstack object store, configured with `temporary url <https://docs.openstack.org/swift/latest/api/temporary_url_middleware.html>` configured (no openstack users is required). This is currently the only way to store documents from chill;
-* a mailer service (SMTP)
-* (optional) a service for verifying phone number. Currently, only Twilio is possible;
-* (optional) a service for sending Short Messages (SMS). Currently, only Ovh is possible;
-
-The `docker-compose.yaml` file of chill app is a basis for a production install. The environment variable in the ```.env``` and ```.env.prod``` should be overriden by environment variables, or ```.env.local``` files.
-
-This should be adapted to your needs:
-
-* The image for php and nginx apps are pre-compiled images, with the default configuration and bundle. If they do not fullfill your needs, you should compile your own images.
-
-   .. TODO:
-
-      As the time of writing (2022-07-03) those images are not published yet.
-
-* Think about how you will backup your database. Some adminsys find easier to store database outside of docker, which might be easier to administrate or replicate.
-
-Run migrations on each update
-=============================
-
-Every time you start a new version, you should apply update the sql schema:
-
-- running ``bin/console doctrine:migration:migrate`` to run sql migration;
-- synchonizing sql views to the last state: ``bin/console chill:db:sync-views``
-
-Cron jobs
-=========
-
-The command :code:`chill:cron-job:execute` should be executed every 15 minutes (more or less).
-
-This command should never be executed concurrently. It should be not have more than one process for a single instance.
-
-Post-install tasks
-==================
-
-- import addresses. See :ref:`addresses`.
-
-
-Tweak symfony messenger
-=======================
-
-Calendar sync is processed using symfony messenger.
-
-You can tweak the configuration
-
-Going further:
-
-* Configure the saml login and synchronisation with Outlook api