From 02c19af6f834e6cc0b4ef7f0a2cdc949b27afd51 Mon Sep 17 00:00:00 2001
From: hawkspar <quentin.chevalier@polytechnique.edu>
Date: Sun, 16 Dec 2018 11:30:39 +0100
Subject: [PATCH] Renommage ldap_config, memo JSDoc
---
.gitignore | 1 -
configfile_doc.json => jsdoc_config.json | 2 +-
ldap_config.json | 2 +-
notes/CONTRIBUTING.json | 5 +--
notes/CONTRIBUTING.md | 5 ++-
notes/memo_jsdoc.json | 4 +++
notes/memo_jsdoc.md | 40 ++++++++++++++++++++++++
notes/memo_knexjs.md | 3 --
notes/memo_postgresql.md | 5 +--
notes/memos.json | 8 +++++
notes/memos.md | 4 +++
package.json | 2 +-
12 files changed, 65 insertions(+), 16 deletions(-)
rename configfile_doc.json => jsdoc_config.json (93%)
create mode 100644 notes/memo_jsdoc.json
create mode 100644 notes/memo_jsdoc.md
create mode 100644 notes/memos.json
create mode 100644 notes/memos.md
diff --git a/.gitignore b/.gitignore
index 3ce63dd..569d214 100644
--- a/.gitignore
+++ b/.gitignore
@@ -72,5 +72,4 @@ build/
# Config files
ldap_credentials.json
-ldap_connexion_config.json
.env
\ No newline at end of file
diff --git a/configfile_doc.json b/jsdoc_config.json
similarity index 93%
rename from configfile_doc.json
rename to jsdoc_config.json
index 72d6252..db17ea2 100644
--- a/configfile_doc.json
+++ b/jsdoc_config.json
@@ -1,5 +1,5 @@
{
- "comment": "Ce fichier sert à configurer JSDoc et permet la génération automatique de documentation facilement 129.104.201.90:389",
+ "comment": "Ce fichier sert à configurer JSDoc et permet la génération automatique de documentation facilement",
"plugins": ["plugins/markdown", "plugins/summarize", "node_modules/jsdoc-babel"],
"recurseDepth": 5,
"source": {
diff --git a/ldap_config.json b/ldap_config.json
index c8a32cc..5171f95 100644
--- a/ldap_config.json
+++ b/ldap_config.json
@@ -1,7 +1,7 @@
{
"comment_1": "Tout ce fichier sert à protéger les vrais champs du LDAP dans les scripts dans src/ldap. Les champs ci-dessous contiennent le nécessaire à une première connexion par exemple.",
"server_prod": "ldap://frankiz.eleves.polytechnique.fr:389",
- "server_dev": "???",
+ "server_dev": "ldap://localhost:389",
"comment_2": "Noms de domaines dans LDAP ; le niv d'après est en uid=, voir Wikipedia",
"dn_groups":"ou=groups,dc=frankiz,dc=net",
diff --git a/notes/CONTRIBUTING.json b/notes/CONTRIBUTING.json
index 73e4bf5..03bd9b0 100644
--- a/notes/CONTRIBUTING.json
+++ b/notes/CONTRIBUTING.json
@@ -1,7 +1,4 @@
{
"title": "Contribuer au projet",
- "children": [
- "memo_knexjs",
- "memo_postgresql"
- ]
+ "children": []
}
\ No newline at end of file
diff --git a/notes/CONTRIBUTING.md b/notes/CONTRIBUTING.md
index 6d12e1a..553fc8d 100644
--- a/notes/CONTRIBUTING.md
+++ b/notes/CONTRIBUTING.md
@@ -163,6 +163,8 @@ https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/awai
## Outils de développement
+Le détail des outils les plus technique est dans {@tutorial memos}.
+
### ESLint
On utilise ESLint pour standardiser le style du code.
@@ -199,4 +201,5 @@ dans une autre pour avoir un environnement de développement agréable.
## Contact
Le BR 2016, plus particulièrement Wilson Jallet, Guillaume Wang, Quentin Chevalier et Anatole Romon
-Le BR 2017, plus particulièrement Olivér Facklam, Grégoire truc et Hardien Renaud
+
+Le BR 2017, plus particulièrement Olivér Facklam, Grégoire Grzeckowicz et Hadrien Renaud
diff --git a/notes/memo_jsdoc.json b/notes/memo_jsdoc.json
new file mode 100644
index 0000000..fc05905
--- /dev/null
+++ b/notes/memo_jsdoc.json
@@ -0,0 +1,4 @@
+{
+ "title": "Memo JSDoc",
+ "children": []
+}
\ No newline at end of file
diff --git a/notes/memo_jsdoc.md b/notes/memo_jsdoc.md
new file mode 100644
index 0000000..20abef6
--- /dev/null
+++ b/notes/memo_jsdoc.md
@@ -0,0 +1,40 @@
+JSDoc, c'est l'outil de génération automatique de documentation. Il transforme des commentaires et des fichiers Markdown comme celui-ci en une masse de pages web lisibles même par un autiste semi-aveugle à quiil manquerait un module de sémantique.
+
+La doc de JSDoc, paradoxalement un peu aride : [`Use JSDoc`](http://usejsdoc.org/)
+
+## Les bases
+
+JSDoc fonctionne sur la base de token de la forme @truc dans des commentaires avec seulement 2 *. C'est en lisant ces tokens qu'il génère sa documentation. JSDoc comprend le javascript, mais ne génère pas automatiquement les tags à partir du code. Ex :
+
+```
+/**
+ * @function renv Fonction bidon
+ * @arg a - Nombre à renvoyer
+ */
+function renv(a:number) { return a; }
+```
+Là on lui donne uyne description d'une fonction et une documentation de son argument, mais pas le type de a, qu'il n'infère pas seul. Ca peut mener à des différences entre le vrai type et le type documenté, surtout quand le code évolue vite, mais ça peut aussi permettre de configurer complètement la doc à la fonction près, ce qui est pas mal non plus.
+
+JSDoc est configuré via le fichier [`jsdoc_config.json`](..\jsdoc_config.json) à la racine du projet. Ce fichier précise à JSDoc quels fichiers traiter, où ranger ses résultats, quels extensions utiliser, etc...
+
+Pour lancer jsdoc la commande est : `jsdoc --configure jsdoc_config.json`
+
+Ou plus simplement : `npm run doc` pour un [`package.json`](..\package.json) Ã jour.
+
+Nous avons fait le choix de ne pas mettre la documentation de sigma sur le git car les nombreux fichiers html alourdissaient inutilement le répertoire. Tout nouveau développeur du projet est donc invité à lanncer JSDoc pour régénérer la doc en local !
+
+## Les détails
+
+### JSDoc et VSCode
+
+JSDoc et VSCode marchent très bien ensemble ; VSCode générera automatiquement les tags afférents à une fonction déjà rédigée si vous commencez un commentaire juste avant cete fonction.
+
+### L'arborescence
+
+JSDoc n'est pas bon pour faire appraître une arborescence de fichiers. Il va afficher toutes les fonctions qu'il parse sur la page d'accueil, indépendamment de leur nombre ou de leur emplacement dans le projet. Pour rendre la documentation lisible et faire apparître une vraie arborescence, il convient d'utiliser des namespace ou des classes, quitte à ce qu'elles soient purement statiques, pour factoriser le code par bloc de sens.
+
+La factorisation de code dans des classes étant en soit une bonne pratique et permettant aussi au développeur de réfléchir à l'organisation de son programme, cette pratique devrait être encouragée de manière globale dans tout le projet.
+
+### Les fichiers. md
+
+JSDoc a deux façons simples d'intégrer des fichiers Mardown dans la doc ; un README en page d'accueil, ou un tutoriel comme celui-ci. Tous les tutoriels doivent être mis dans le même dossier avec des fichiers de config .json pour définir une arborescence de tutoriels propres.
\ No newline at end of file
diff --git a/notes/memo_knexjs.md b/notes/memo_knexjs.md
index 842de16..ce2f105 100644
--- a/notes/memo_knexjs.md
+++ b/notes/memo_knexjs.md
@@ -1,6 +1,3 @@
-Mémo d'introduction à Knex.js pour les nuls
-===
-
```info
Note : ce mémo a été rédigé à l'origine pour le CONTRIBUTING.md de shitpost-backend, donc fait parfois référence à des fichiers de ce projet. C'est indiqué à chaque fois lorsque c'est le cas.
```
diff --git a/notes/memo_postgresql.md b/notes/memo_postgresql.md
index 40092d6..80c5d53 100644
--- a/notes/memo_postgresql.md
+++ b/notes/memo_postgresql.md
@@ -1,9 +1,6 @@
-Mémo d'introduction à PostgreSQL pour les nuls
-===
-
Dans un premier temps, on part du principe que l'utilisateur travaille en local, i.e. gère des bases de données (BDDs) locales sur une machine où il a tout contrôle. Les points à adapter dans le cas d'une base de donnée distante, ou d'une utilisation sans droits d'admin, sont traités dans la section correspondante.
-La doc de PostgreSQL, admirablement bien faite, lisible et accessible : https://www.postgresql.org/docs/current/static/tutorial.html
+La doc de PostgreSQL, admirablement bien faite, lisible et accessible : [`ici`](https://www.postgresql.org/docs/current/static/tutorial.html)
## Les bases
diff --git a/notes/memos.json b/notes/memos.json
new file mode 100644
index 0000000..0777b45
--- /dev/null
+++ b/notes/memos.json
@@ -0,0 +1,8 @@
+{
+ "title": "Memos",
+ "children": [
+ "memo_knexjs",
+ "memo_postgresql",
+ "memo_jsdoc"
+ ]
+}
\ No newline at end of file
diff --git a/notes/memos.md b/notes/memos.md
new file mode 100644
index 0000000..1f51b82
--- /dev/null
+++ b/notes/memos.md
@@ -0,0 +1,4 @@
+Mémos
+===
+
+Le projet sigma était assez large et comportant pas mal de facettes avec des technologies pas forcément toujours intuitives ou bien documentées, les mémos de cetten section sont là pour permettre au dev perdu de s'y retrouver rapidement face à une technologie qu'il ne maîtrise pas à fond.
\ No newline at end of file
diff --git a/package.json b/package.json
index dc3c2d8..d661aad 100644
--- a/package.json
+++ b/package.json
@@ -8,7 +8,7 @@
"watch": "webpack --watch --mode development",
"start": "nodemon --watch build ./build/bundle.js",
"start_prod": "node ./build/bundle.js",
- "doc": "jsdoc --configure configfile_doc.json",
+ "doc": "jsdoc --configure jsdoc_config.json",
"lint": "eslint --ext .js --ext .ts src/",
"test": "mocha --exit"
},
--
GitLab