fix(doc): utilise mkdocs pour générer la documentation #148

.github/workflows/api-ci.yml

@@ -94,32 +94,4 @@ jobs:
         if: github.ref == 'refs/heads/master'
         run: docker push caminofr/camino-api:${GITHUB_SHA}
 
-  doc:
-    needs: [unit-test, integration-test]
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v3
-      - name: Use Node.js
-        uses: actions/setup-node@v3
-        with:
-          node-version: '17.8'
-          cache: 'npm'
-      - name: Generate docs
-        run: |
-          npm ci
-          npm run docs -w packages/api
-        env:
-          CI: true
-      - name: Build Docker image
-        run: docker build -f Dockerfile.api.docs -t caminofr/camino-api-docs:${GITHUB_SHA} .
-      - name: Login to Docker Hub
-        uses: docker/login-action@v1
-        with:
-          username: ${{ secrets.DOCKER_USERNAME }}
-          password: ${{ secrets.DOCKER_TOKEN }}
-      - name: Push Docker image to the Docker Hub
-        if: github.ref == 'refs/heads/master'
-        run: docker push caminofr/camino-api-docs:${GITHUB_SHA}
-
 

.github/workflows/doc-ci.yml

+name: doc/ci
+on:
+  push:
+    branches-ignore:
+      - release-candidate
+concurrency:
+  group: doc-ci-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  doc:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: '3.10'
+          cache: 'pip'
+      - name: Generate docs
+        run: make docs/build
+      - name: Build Docker image
+        run: docker build -f Dockerfile.api.docs -t caminofr/camino-api-docs:${GITHUB_SHA} .
+      - name: Login to Docker Hub
+        uses: docker/login-action@v1
+        with:
+          username: ${{ secrets.DOCKER_USERNAME }}
+          password: ${{ secrets.DOCKER_TOKEN }}
+      - name: Push Docker image to the Docker Hub
+        if: github.ref == 'refs/heads/master'
+        run: docker push caminofr/camino-api-docs:${GITHUB_SHA}
+
+

.gitignore

@@ -5,3 +5,5 @@ node_modules
 /.cache
 packages/ui/storybook-static/
 .vault
+/docs
+/*.csv

Dockerfile.api.docs

 FROM nginx
-COPY packages/api/docs /usr/share/nginx/html
+COPY docs /usr/share/nginx/html

Makefile

+_docs:
+	cd docs-sources && pip install -r requirements.txt
+
+docs/build: _docs
+	cd docs-sources && mkdocs build -d ../docs
+docs/serve: _docs
+	cd docs-sources && mkdocs serve -a localhost:8080
\ No newline at end of file

packages/api/docs-sources/assets/database/generate → docs-sources/assets/database/generate

@@ -3,4 +3,5 @@ set eufo -pipefail
 
 planter postgres://postgres:password@localhost/camino?sslmode=disable -o camino-db.uml
 
-cat camino-db.uml | docker run --rm -i agileek/plantuml:1.2022.3 > camino-db.svg
\ No newline at end of file
+cat camino-db.uml | docker run --rm -i agileek/plantuml:1.2022.3 > camino-db.svg
+cp camino-db.svg ../../docs/img
\ No newline at end of file

packages/api/docs-sources/assets/generate → docs-sources/assets/generate

 #!/bin/bash
 set eufo -pipefail
 
-cat architecture.puml | docker run --rm -i agileek/plantuml:1.2022.3 > architecture.svg
\ No newline at end of file
+cat architecture.puml | docker run --rm -i agileek/plantuml:1.2022.3 > architecture.svg
+cp architecture.svg ../docs/img
\ No newline at end of file

packages/api/docs-sources/01-utilisation/01-introduction.md → docs-sources/docs/01-utilisation/01-introduction.md

@@ -4,5 +4,5 @@
 
 L'API de Camino propose deux manières d'interagir:
 
-- {@page API GraphQL} (complète)
-- {@page API Rest} (interaction limitée)
+- [complète](02-graphql.md)
+- [interaction limitée](03-rest.md)

packages/api/docs-sources/02-developpement/01-introduction.md → docs-sources/docs/02-developpement/01-introduction.md

@@ -69,8 +69,6 @@ npm run start -w packages/api
 ```bash
 .
 │
-├── docs-sources         # `source de la documentation générée avec typeDoc`
-│
 └── src                  # `fichiers sources. Transformés avec npm run build.`
     ├── index            # `point d'entrée`
     │

packages/api/docs-sources/02-developpement/02-base-de-donnees.md → docs-sources/docs/02-developpement/02-base-de-donnees.md

@@ -2,7 +2,7 @@
 
 L'Api Camino fonctionne avec une base de données PostgreSQL.
 
-![camino database schema](media://database/camino-db.svg)
+![camino database schema](../img/camino-db.svg)
 
 ## Chargement des données
 

packages/api/docs-sources/03-architecture/01-introduction.md → docs-sources/docs/03-architecture/01-introduction.md

 # Architecture de l'application Camino
 
-![architecture](media://architecture.svg)
+![architecture](../img/architecture.svg)
 
 ## Ansible