ci: génère la documentation automatiquement (#431)

.eslintignore

@@ -4,6 +4,6 @@
 /dist
 /docs
 /files
-/manual
+/docs-sources
 /node_modules
 /sources

.github/workflows/docs.yml

@@ -0,0 +1,33 @@
+name: Docs
+
+on:
+  release:
+    branches:
+      - master
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v1
+      - name: Use Node.js
+        uses: actions/setup-node@v1
+        with:
+          node-version: 12
+      - name: Generate docs
+        run: |
+          npm ci
+          npm run docs
+        env:
+          CI: true
+      - name: Build Docker image
+        run: docker build -f Dockerfile.docs . --tag caminofr/camino-api-docs
+      - name: Push Docker image to the Docker Hub
+        run: |
+          docker login --username "$DOCKER_USERNAME" --password "$DOCKER_PASSWORD"
+          docker push caminofr/camino-api-docs
+        env:
+          DOCKER_USERNAME: ${{ secrets.DOCKER_USERNAME }}
+          DOCKER_PASSWORD: ${{ secrets.DOCKER_PASSWORD }}

Dockerfile.docs

@@ -0,0 +1,3 @@
+FROM nginx
+COPY default.conf.template /etc/nginx/templates/default.conf.template
+COPY docs /usr/share/nginx/html

README.md

@@ -1,4 +1,4 @@
-# Camino API
+# API de Camino
 
 [![Tests Status][ci-img]][ci] [![codecov][codecov-img]][codecov] [![Dependency Status][dep-img]][dep]
 
@@ -9,180 +9,21 @@
 [dep-img]: https://david-dm.org/MTES-MCT/camino-api.svg
 [dep]: https://david-dm.org/MTES-MCT/camino-api
 
-> API GraphQL de [Camino](http://camino.beta.gouv.fr/): [api.camino.beta.gouv.fr](https://api.camino.beta.gouv.fr)
+> API de Camino, le cadastre minier numérique ouvert: [api.camino.beta.gouv.fr](https://api.camino.beta.gouv.fr)
 
----
-
-## Technologies
-
-- [TypeScript](https://typescriptlang.org/)
-- [Node.js](https://nodejs.org/)
-- [Express.js](http://expressjs.com)
-- [PostgreSQL](https://www.postgresql.org/)
-- [Express-GraphQL](https://github.com/graphql/express-graphql)
-- [Knex.js](https://knexjs.org/)
-- [Objection.js](http://vincit.github.io/objection.js/)
-- [Eslint](https://eslint.org/)
-- [Prettier](https://prettier.io/)
-- [Standardjs](https://standardjs.com/)
-- [Docker](https://www.docker.com/)
-
----
-
-## Environnement
-
-- Node.js (v.10 ou plus) et npm
-- PostgreSQL (v.10 ou plus)
-
----
-
-## Utilisation
-
-### Configuration et imports des données
-
-- Cloner ce repo : `git clone https://github.com/MTES-MCT/camino-api.git`.
-- Renommer le fichier `.env-example` en `.env` et le compléter.
-- Créer une base de données PostgreSQL correspondant au fichier `.env`.
-- À l'intérieur du dossier `/backups`, coller le fichier `camino-public.sql` disponible ici : [Camino database](https://github.com/MTES-MCT/camino-database).
-
-### Installation
-
-```bash
-# installe les dépendances
-npm install
-
-# importe les données depuis /database/camino-public.sql
-npm run db:public-import
-
-# crée un utilisateur admin
-npm run db:user
-```
-
-### Développement
-
-```bash
-# démarre le serveur avec nodemon
-npm run dev
-```
-
-### Production
-
-```bash
-# compile l'application avec typescript
-npm run build
-
-# démarre le serveur
-npm run start
-```
-
----
-
-## Tests
-
-### Tests unitaires
-
-```sh
-# lance les tests en local
-npm run test:jest
-```
-
-### Tests de bout-en-bout
-
-Ces tests sont lancés depuis `camino-ui` avec la commande `npm run test:cypress`.
-
-Pour que cela fonctionne l'API doit être lancée avec `npm run dev`.
-
-Pour que les tests soient plus rapides, on peut utiliser une version publique de la base de données contenant seulement certains titres miniers.
-
-```bash
-# crée une copie de la base de données (publique)
-npm run db:dump-public
-
-# importe la base de données publique
-# met à jour les données (daily)
-# crée un utilisateur super-admin
-# lance le serveur de dev
-npm run test:cypress
-```
+L'API de Camino expose les caractéristiques des titres et autorisations du domaine minier français. Elle permet aux utilisateurs autorisés de gérer ces titres et autorisations. Pour plus de détail sur le périmètre de l'application, voir [cette page](https://camino.beta.gouv.fr/a-propos).
 
 ---
 
 ## Documentation
 
-La documentation [est disponible ici](https://github.com/MTES-MCT/camino-api/tree/master/manual).
-
----
-
-## Structure des fichiers
-
-```bash
-.
-│
-├── dev                  # `scripts de développement`
-├── knex                 # `scripts de création et d'import de la base de données (npm run migrate)
-│   ├── migrations       # `création de la base de données`
-│   └── seeds            # `import depuis les fichier /sources vers la base de données`
-│
-├── manual               # `source de la documentation générée avec esdoc`
-│
-└── src                  # `fichiers sources. Transformés avec npm run build.`
-    ├── index            # `point d'entrée`
-    │
-    ├── api              # `APIs`
-    │   ├── graphql      # `API Graphql`
-    │   └── rest         # `API Rest`
-    │
-    ├── config           #
-    │   ├── index        # `variables globales`
-    │   └── knex         # `connexion à la base de données`
-    │
-    ├── database         # `base de données PostgreSQL`
-    │   ├── models       # `modèles de la base de données (knex.js / objection.js)`
-    │   └── queries      # `requêtes à la base de données (knex.js / objection.js)`
-    │
-    ├── business         # `logique métier`
-    │   ├── processes    # `scripts de traitement`
-    │   ├── rules        # `lois et procédures administratives`
-    │   ├── utils        # `utilitaires de filtrage et de classement`
-    │   ├── daily        # `scripts de mise à jour quotidiens (npm run daily)`
-    │   ├── etape-update # `script effectués lors de la mise à jour d'une étape`
-    │   └── monthly      # `scripts de mise à jour mensuels (npm run monthly)`
-    │
-    └── tools            # `outils`
-        ├── export       # `exportation de la base de données vers des spreadsheets (npm run export)`
-        ├── import       # `import de spreadsheets vers des fichiers json dans /sources (npm run import)`
-        ├── api-...      # `connexion aux api externes`
-        └── emails-send  # `envoi d'email`
-
-```
-
----
-
-## Base de données
-
-![camino database schema](manual/database/camino-db.svg)
-
----
-
-## Contribution
-
-Voir [contributing.md](contributing.md) (en anglais) pour plus d'infos.
+La documentation de l'API est disponible ici: [docs.camino.beta.gouv.fr](https://docs.camino.beta.gouv.fr).
 
 ---
 
 ## Crédits
 
-### Production
-
-- [La Fabrique Numérique, Ministère de la transition écologique et solidaire](https://www.ecologique-solidaire.gouv.fr/inauguration-fabrique-numerique-lincubateur-des-ministeres-charges-lecologie-et-des-territoires)
-
-### Équipe
-
-- Guillaume Levieux, intrapreneur
-- Joeffrey Arruyer, coach
-- [François Romain](https://francoisromain.com), développeur
-- [Adrien Risser](https://github.com/risseraka), développeur
-- [Nicolas Petitot](https://github.com/NeoBahamut), développeur
+[La Fabrique Numérique, Ministère de la transition écologique et solidaire](https://www.ecologique-solidaire.gouv.fr/inauguration-fabrique-numerique-lincubateur-des-ministeres-charges-lecologie-et-des-territoires)
 
 ---
 

default.conf.template

@@ -0,0 +1,14 @@
+server {
+    listen       ${NGINX_PORT};
+    server_name  localhost;
+
+    location / {
+        root   /usr/share/nginx/html;
+        index  index.html index.htm;
+    }
+
+    error_page   500 502 503 504  /50x.html;
+    location = /50x.html {
+        root   /usr/share/nginx/html;
+    }
+}

dev/api/graphql-dsl-to-query-convert.js

@@ -11,7 +11,7 @@ fetch(url, {
   .then(res => res.json())
   .then(res =>
     fs.writeFileSync(
-      'manual/api/schema.json',
+      'docs-sources/api/schema.json',
       JSON.stringify(res.data, null, 2)
     )
   )

docker-compose.docs.yml

@@ -0,0 +1,19 @@
+version: '3'
+
+services:
+  app:
+    image: caminofr/camino-api-docs
+    environment:
+      VIRTUAL_HOST: ${URL}
+      VIRTUAL_PORT: ${PORT}
+      LETSENCRYPT_HOST: ${URL}
+      LETSENCRYPT_EMAIL: ${LETSENCRYPT_EMAIL}
+      NGINX_PORT: ${PORT}
+    expose:
+      - ${PORT}
+    restart: always
+
+networks:
+  default:
+    external:
+      name: nginx-proxy

docs-sources/01-utilisation/01-introduction.md

@@ -0,0 +1,8 @@
+# Utilisation de l'API de Camino
+
+> [api.camino.beta.gouv.fr](https://api.camino.beta.gouv.fr)
+
+L'API de Camino propose deux manières d'interagir:
+
+- {@page API GraphQL} (complète)
+- {@page API Rest} (interaction limitée)

manual/api/readme.md → docs-sources/01-utilisation/02-graphql.md

@@ -1,30 +1,34 @@
-# Api GraphQL
+# Api GraphQL de Camino
 
-- [Documentation offcielle de GraphQL](https://graphql.org/)
+L'API GraphQl de Camino est accessible à cette url: [api.camino.beta.gouv.fr/](https://api.camino.beta.gouv.fr/).
 
-## Requêtes avec _GraphiQL_
+La documentation de cette API est consultable dans l'onglets `Docs` (en haut à droite) de l'application _GraphiQL_.
 
-_GraphiQL_ est une application qui permet de tester une API GraphQL dans un navigateur. Pour Camino, elle est accessible à l'url racine de l'API: https://api.camino.beta.gouv.fr/.
+## _GraphiQL_
 
-_GraphiQL_ expose une documentation de l'API qui est accessible en cliquant sur le bouton `Docs` (en haut à droite).
+_GraphiQL_ est une application qui permet de consulter la documentation et de tester une API GraphQL dans un navigateur. Concernant l'API Camino, cette application est accessible à l'url racine de l'API: [api.camino.beta.gouv.fr/](https://api.camino.beta.gouv.fr/).
 
 Des exemples de requêtes se trouvent dans [ce dossier](https://github.com/MTES-MCT/camino-api/blob/master/tests/queries/).
 
 ### Requêtes simples
 
 Par exemple, pour obtenir la liste des substances:
 
-- copier une requête dans le champs principal de l'interface de _GraphiQL_: [substances.graphql](https://github.com/MTES-MCT/camino-api/blob/master/manual/api/queries/substances.graphql)
-- valider en cliquant sur le bouton "play"
+- copier une requête dans le champs principal de l'interface de _GraphiQL_: [substances.graphql](https://github.com/MTES-MCT/camino-api/blob/master/tests/queries/substances.graphql)
+- valider en cliquant sur le bouton `▶`.
 
 ### Requêtes avec des variables
 
 Certaines requêtes nécessitent le passage de variables. Par exemple, pour obtenir la liste des titres:
 
-- copier la requête dans le champs principal de l'interface de _GraphiQL_: [titres.graphql](https://github.com/MTES-MCT/camino-api/blob/master/manual/api/queries/titres.graphql)
-- copier les variables dans le champs `query variables` (en bas à gauche de l'écran): [titres-variables.json](https://github.com/MTES-MCT/camino-api/blob/master/manual/api/queries/titres-variables.json)
-- valider en cliquant sur le bouton "play"
+- copier la requête dans le champs principal de l'interface de _GraphiQL_: [titres.graphql](https://github.com/MTES-MCT/camino-api/blob/master/tests/queries/titres.graphql)
+- copier les variables dans le champs `query variables` (en bas à gauche de l'écran): [titres-variables.json](https://github.com/MTES-MCT/camino-api/blob/master/tests/queries/titres-variables.json)
+- valider en cliquant sur le bouton `▶`.
 
 ### Requêtes nécessitant une authentification
 
-Certaines requêtes sont protégées et nécessitent une authentification par token (jwt). Pour les tester, il faut passer le token dans le header http de la requête. Cela n'est pas possible avec l'interface _GraphiQL_. C'est possible avec [GraphQL Playground](https://github.com/prisma/graphql-playground), [GraphiQL App](https://github.com/skevy/graphiql-app) ou une application pour faire des requêtes http ([exemple](https://github.com/MTES-MCT/camino-api/blob/master/manual/api/test.http)).
+Certaines requêtes sont protégées et nécessitent une authentification par token (jwt). Pour les tester, il faut passer le token dans le header http de la requête. Cela n'est pas possible avec _GraphiQL_. C'est possible avec [GraphQL Playground](https://github.com/prisma/graphql-playground), [GraphiQL App](https://github.com/skevy/graphiql-app).
+
+### Liens
+
+- [Documentation offcielle de GraphQL](https://graphql.org/)

docs-sources/01-utilisation/03-rest.md

@@ -0,0 +1 @@
+# Api Rest de Camino