Amélioration de la documentation (numerique-gouv#73)

* Improve documentation * Add doc for forms * Add syntax highlighting * Update deploy-doc version * Fix README * .py → .python * Update doc * Add doc for components * style * Add resource pages for icons and pictograms * Add resource pages for icons and pictograms * Move doc in a tab panel * Improve text * Improve text * Improve style * sensible number of rows for textarea samples * detail * typo * Update example_app/templates/example_app/blocks/header.html Co-authored-by: Agnès Haasser <[email protected]> --------- Co-authored-by: Agnès Haasser <[email protected]>
B-Alica · Nov 13, 2023 · ec945c5 · ec945c5
1 parent 2e71b1e
commit ec945c5
Show file tree

Hide file tree

Showing 22 changed files with 862 additions and 110 deletions.
diff --git a/.github/workflows/deploy-doc.yml b/.github/workflows/deploy-doc.yml
@@ -13,7 +13,7 @@ jobs:
     strategy:
       max-parallel: 4
       matrix:
-        python-version: [3.9]
+        python-version: ["3.11"]
 
     steps:
     - uses: actions/checkout@v2

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -14,7 +14,7 @@ repos:
   rev: 23.10.1
   hooks:
     - id: black
-      language_version: python3.10
+      language_version: python3.11
       args:
         - --line-length=88
 - repo: https://github.com/PyCQA/bandit

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -6,15 +6,15 @@ L’installation a été testée sur Ubuntu 22.04 avec Python 3.10 et poetry ins
 - Faire un `git clone` du projet sur votre machine et ouvrir un terminal
 
 - Installer l’environnement virtuel, les dépendances, les *pre-commit hooks* et initialiser le site d’exemple :
-```
+```{ .bash }
 make init
 ```
 
 ## Tests
 
 Pour faire tourner les tests :
 
-```
+```{ .bash }
 make test
 ```
 
@@ -24,24 +24,24 @@ Le projet utilise [Poetry](https://python-poetry.org/) pour gérer les dépendan
 
 Pour installer les dépendances du projet :
 
-```
+```{ .bash }
 poetry install
 ```
 
 Pour installer un nouveau paquet et l’ajouter aux dépendances :
 
-```
+```{ .bash }
 poetry add <paquet>
 ```
 
 Pour un paquet ne servant que pour le développement, par exemple `black` :
 
-```
+```{ .bash }
 poetry add --group dev <paquet>
 ```
 
 Pour activer l’environnement virtuel :
-```
+```{ .bash }
 poetry shell
 ```
 
@@ -58,22 +58,23 @@ Concernant les langues :
 
 Pour vérifier son code, on peut intégrer le linter adapté à son IDE et aussi faire ceci :
 
-```
+```{ .bash }
 make checkstyle
 ```
 
 Une vérification automatique est faite via des *pre-commit hooks*, qui ont normalement été installés via le `make init`.
 
 Il est possible de les mettre à jour avec la commande :
 
-```
+```{ .bash }
 pre-commit update
 ```
 
 ## Mise à jour du système de design
 
-Quand une nouvelle version du système de design de l’État est publiée, il est possible de le mettre à jour automatiquement via la commande
-```
+Quand une nouvelle version du système de design de l’État est publiée, il est possible de le mettre à jour automatiquement via la commande :
+
+```{ .bash }
 make update_dsfr
 ```
 

diff --git a/INSTALL.md b/INSTALL.md
@@ -0,0 +1,65 @@
+# Installation de django-DSFR
+
+## Installation basique
+
+- Installez le paquet
+
+```{ .bash }
+pip install django-dsfr
+```
+
+- Ajoutez `widget_tweaks` et `dsfr` à `INSTALLED_APPS` dans le `settings.py` avant la ou les app avec laquelle vous voulez l’utiliser :
+
+```{ .python }
+INSTALLED_APPS = [
+    ...
+    "widget_tweaks"
+    "dsfr",
+    <votre_app>
+]
+```
+
+- Ajouter les lignes suivantes dans la section `TEMPLATES` du `settings.py` pour faire fonctionner les formulaires :
+
+```{ .python }
+TEMPLATES = [
+    {
+        [...]
+        "DIRS": [
+            os.path.join(BASE_DIR, "dsfr/templates"),
+            os.path.join(BASE_DIR, "templates"),
+        ],
+    },
+]
+```
+
+- Ajouter le `FORM_RENDERER` in `settings.py` pour faire fonctionner les formulaires :
+
+```{ .python }
+FORM_RENDERER = "django.forms.renderers.TemplatesSetting"
+```
+
+- Inclure les tags dans votre fichier `base.html` (voir par exemple sur [base.html](https://github.com/numerique-gouv/django-dsfr/blob/main/example_app/templates/example_app/base.html))
+
+- Lancer le serveur (`python manage.py runserver`) et aller sur [http://127.0.0.1:8000/](http://127.0.0.1:8000/)
+
+
+## Installation avancée (optionnelle)
+### Utilisation de la conf en admin
+- Ajoutez le `context_processor` au fichier `settings.py` :
+
+```{ .python }
+TEMPLATES = [
+    {
+        [...]
+        "OPTIONS": {
+            "context_processors": [
+                [...]
+                "dsfr.context_processors.site_config",
+            ],
+        },
+    },
+]
+```
+
+- Créez un objet "DsfrConfig" dans le panneau d’administration
diff --git a/README.rst b/README.rst
@@ -29,56 +29,4 @@ Tested with Python 3.7 to 3.11 and Django 3.2 to 4.2. Per `vermin <https://githu
 Quick start
 -----------
 
-1. Install with :code:`pip install django-dsfr`.
-
-2. Add "widget_tweaks" and "dsfr" to INSTALLED_APPS in your settings.py like this, before the app you want to use it with::
-
-    INSTALLED_APPS = [
-        ...
-        "widget_tweaks"
-        "dsfr",
-        <your_app>
-    ]
-
-3. In order to use forms and formsets, add to INSTALLED_APPS in your settings.py::
-
-	INSTALLED_APPS = [
-        ...
-        "django.forms",
-		"widget_tweaks",
-		"crispy_forms",
-    ]
-
-4. Add the following info in the TEMPLATES section in your settings.py so that the choice forms work::
-
-    TEMPLATES = [
-        {
-            [...]
-            "DIRS": [
-                os.path.join(BASE_DIR, "dsfr/templates"),
-                os.path.join(BASE_DIR, "templates"),
-            ],
-        },
-    ]
-
-5. Add the following FORM_RENDERER in settings.py so that the choice forms work::
-
-    FORM_RENDERER = "django.forms.renderers.TemplatesSetting"
-
-6. (Optional) Add the context processor to your settings.py and create an instance of "DsfrConfig" in the admin panel::
-
-    TEMPLATES = [
-        {
-            [...]
-            "OPTIONS": {
-                "context_processors": [
-                    [...]
-                    "dsfr.context_processors.site_config",
-                ],
-            },
-        },
-    ]
-
-7. Include the tags in your base.html file (see example file at https://github.com/numerique-gouv/django-dsfr/blob/main/example_app/templates/example_app/base.html)
-
-8. Start the development server and visit http://127.0.0.1:8000/
+See the `INSTALL.md <INSTALL.md>`_ file.
diff --git a/doc/components.md b/doc/components.md
@@ -0,0 +1,36 @@
+Le système de design propose [un certain nombre de composants](https://www.systeme-de-design.gouv.fr/elements-d-interface/composants), et Django-DSFR vise à les implémenter sous forme de balises utilisables dans les templates Django, soit en passant directement les paramètres, soit en les passant depuis la vue via un dictionnaire.
+
+Par exemple, il est possible de créer un bouton soit en passant directement les paramètres :
+
+```{.django}
+{% dsfr_button label="Bouton principal" onclick="alert('Vous avez cliqué sur le bouton principal')" %}
+```
+
+Soit en définissant un dictionnaire dans la vue :
+
+```{ .python }
+context["data_dict"] = {
+    "label": "Bouton principal",
+    "onclick": "alert('Vous avez cliqué sur le bouton principal')",
+}
+```
+
+et en l’appelant depuis le template :
+
+```{.django}
+{% dsfr_button data_dict %}
+```
+
+L’implémentation de ces balises est un travail en cours, mais il est tout à fait possible d’utiliser directement l’ensemble du système de design de l’État en utilisant directement le code HTML tel que défini dans la documentation officielle :
+
+```{.html}
+<button class="fr-btn" onclick="alert('Vous avez cliqué sur le bouton principal')" type="submit">
+  Bouton principal
+</button>
+```
+
+Toutes ces options produisent le même résultat :
+
+<button class="fr-btn" onclick="alert('Vous avez cliqué sur le bouton principal')" type="submit">
+  Bouton principal
+</button>
diff --git a/doc/forms.md b/doc/forms.md
@@ -0,0 +1,39 @@
+Les formulaires sont construits en se basant sur la classe `DsfrBaseForm`, par exemple :
+
+```{ .python }
+# votre_app/forms.py
+
+from dsfr.forms import DsfrBaseForm
+
+
+class ExampleForm(DsfrBaseForm):
+    # basic fields
+    user_name = forms.CharField(label="Nom d’utilisateur", max_length=100)
+
+    user_email = forms.EmailField(
+        label="Adresse électronique",
+        help_text="Format attendu : [email protected]",
+        required=False,
+    )
+```
+
+Il est possible de multi-classer :
+
+```{ .python }
+class AuthorCreateForm(ModelForm, DsfrBaseForm):
+```
+
+Le formulaire ajoute la ou les classes appropriées (`fr-input`, `fr-select`, etc.) en fonction du type de champ, mais uniquement si une classe n’a pas déjà été ajoutée.
+
+Si c'est le cas, il faut aussi forcer manuellement les classes à utiliser :
+
+```{ .python }
+    password = forms.CharField(
+        label="Mot de passe", widget=forms.PasswordInput(
+            "autocomplete": "current-password",
+            "required": True,
+            "class": "fr-input my-custom-class"
+        )
+    )
+
+```
diff --git a/example/settings.py b/example/settings.py
@@ -44,7 +44,6 @@
     "dsfr",
     "example_app",
     "django_distill",
-    "crispy_forms",
 ]
 
 MIDDLEWARE = [