Ce dépôt contient le code permettant de générer une image Docker contenant l'outillage de base que nous utilisons pour maintenir la documentation de nos projets, c'est-à-dire :
- Hugo, un générateur statique de code, permettant d'afficher en HTML les fichiers de documentation écrits en
markdown. - Un archetype Hugo permettant de générer des ADRs.
- Des scripts permettant de générer facilement un document ou un ADR.
- Un thème basique basé sur Hugo Whisper
- Une instance d'Excalidraw pour réaliser nos schémas.
L'objectif principal d'incaya-documentation est de rendre facilement et rapidement accessible - à la lecture, mais aussi à l'écriture - la documentation de nos projets.
À cette fin, cette documentation est réalisée en markdown dans un répertoire dédié de la base de code, proche du développeur donc. Ainsi, la documentation est directement accessible depuis Github par exemple.
Mais pour la rendre encore plus facilement lisible, on va utiliser Hugo pour l'afficher directement dans l'environnement de développement. Hugo est un générateur de code statique qui va se charger d'afficher en HTML des fichiers .md contenus (et organisés) au sein d'un répertoire content.
L'utilisation basique de l'image incaya-documentation va donc simplement consister à monter le répertoire stockant la documentation du projet dans un répertoire content du conteneur Docker.
Nous sommes aussi convaincus qu'une bonne documentation d'un projet informatique se doit d'inclure des schémas (d'architecture, d'infrastructure ...). Et nous aimons particulièrement la simplicité et l'efficacité d'Excalidraw pour réaliser de tel schéma. Il est donc inclus dans l'image Docker en plus de Hugo.
Il existe deux versions de l'image docker : une avec des contenus en français
ghcr.io/incaya/incaya-documentation:fret l'autre en anglaisghcr.io/incaya/incaya-documentation:en. Selon la langue avec laquelle vous souhaitez gérer votre documentation, pensez à utiliser la bonne image ! Pour les exemples à suivre, on utilise la version française de l'image, qui est celle par défaut.
Soit un projet dont la documentation est contenue dans le répertoire documentations organisé de la manière suivante :
documentations
├── adrs
│ └── adr1.md
└── docs
└── doc1.mdLa présence des répertoires
adrsetdocscorrespond à notre organisation par défaut de la documentation, mais aussi aux menus générés par la configuration d'Hugo. Cela peut être modifié en surchargent cette configuration par défaut, voir la suite "Surchager la configuration"
On lance alors incaya-documentation de la maniére suivante :
docker run --rm --name project-documentation -d \
-v documentations:/documentation/content \
-p 3000:3000 \
-p 1313:1313 \
ghcr.io/incaya/incaya-documentation:frHugo peut aussi utiliser des fichiers spécifiques pour gérer les pages d'accueil (accueil général, accueil documentation, accueil ADR). Vous pouvez générer ses fichiers en ligne de commande depuis le conteneur :
➜ docker exec -it project-documentation bash
root@27f70055675c:/# cd documentation/
root@27f70055675c:/documentation# ./init-doc.sh
Le répertoire de documentation est bien présent.
La documentation est maintenant initialisée.
root@27f70055675c:/documentation# exitLe site de documentation est alors visible sur http://localhost:1313
Excalidraw est accessible sur http://localhost:3000
Bien évidement, la documentation peut être intégrée avec Docker Compose :
version: "3.7"
services:
documentation:
image: ghcr.io/incaya/incaya-documentation:fr
volumes:
- ./documentations:/documentation/content
ports:
- 3000:3000
- 1313:1313Et voici une recette pouvant être ajoutées à un Makefile :
# in Makefile
doc-init: # Setup documentation folder
docker-compose run --rm --no-deps documentation bash -ci '\
cd /documentation && \
./init-doc.sh \
'Hugo utilise les front matter présents dans les fichiers .md, entre autres la propriété weight pour gérer l'ordre des articles.
Il existe un script permettant de générer un nouveau fichier md de documentation avec le front matter prérempli : new-docs.sh.
De la même manière, il existe un script permettant de créer un nouvel ADR : new-docs.sh.
Voici comment les intégrer dans un Makefile :
# in Makefile
doc-new-adr: ## Create a new ADR
docker-compose run --rm --no-deps documentation bash -ci '\
cd /documentation && \
./new-adr.sh \
'
doc-new-doc: ## Create a new file for documentation
docker-compose run --rm --no-deps documentation bash -ci '\
cd /documentation && \
./new-docs.sh \
'L'image Docker est fournie avec une configuration par défaut de Hugo. Cette configuration permet entre autres de définir les menus de site. Il est possible de remplacer cette configuration par défaut par une configuration propre au projet en cours, par exemple dans un fichier hugo-config.toml :
baseURL = "http://localhost"
languageCode = 'en'
defaultContentLanguage = 'en'
title = "My Documentation"
pygmentsCodeFences = true
pygmentsCodefencesGuessSyntax = true
pygmentsUseClasses = true
# Controls how many words are printed in the content summary on the docs homepage.
# See https://gohugo.io/content-management/summaries/
summaryLength = 30
[[menu.main]]
name = "Accueil"
url = "/"
weight = 1
[[menu.main]]
name = "Documentation"
url = "/docs/"
weight = 2
[[menu.main]]
name = "ADR."
url = "/adrs/"
weight = 3
[[menu.main]]
name = "Search"
url = "/search/"
weight = 4
[params]
google_analytics_id=""
homepage_button_link = 'adrs'
homepage_button_text = 'see adrs'
enable_anchor_link = true
mainSections = ['docs', 'adrs', 'search']
footer_link_url = 'https://www.mydomaine/'
footer_link_title = 'mydomaine'
[params.logo]
standard = "images/mylogo.png"Il suffit alors de monter se fichier dans le conteneur Docker, par exemple avec Docker Compose ou l'on change aussi le port de Hugo en 6666 et le port exposé de Excalidraw en 6667:
version: "3.7"
services:
documentation:
image: ghcr.io/incaya/incaya-documentation:en
volumes:
- ./documentations:/documentation/content
- ./logo.png:/documentation/static/images/mylogo.png
- ./hugo-config.toml:/documentation/config.toml
environment:
- HUGO_PORT=6666
ports:
- 6666:6666
- 6667:3000Si l'objectif principal est d'afficher la documentation en environnement de développement, rien n'empêche de profiter d'Hugo pour générer des fichiers statiques de la documentation, pour ensuite les héberger sur un service du type Github Pages ou Netlify.
Hugo générant les fichiers finaux dans un répertoire public :
version: "3.7"
services:
documentation:
image: ghcr.io/incaya/incaya-documentation:fr
volumes:
- ./documentations:/documentation/content
- ./published-documentation:/documentation/public
- ./hugo-config.toml:/documentation/config.toml
ports:
- 3000:3000
- 1313:1313# in Makefile
doc-generate: ## Generate statics for documentation ready for publication
docker-compose run --rm --no-deps documentation bash -ci '\
cd /documentation && \
hugo \
'Et voici un exemple de workflow Github pour automatiser le déploiement :
//in .github/workflows/documentation.yml
name: Doc on GitHub Pages
on:
push:
branches:
- develop # Set a branch to deploy
pull_request:
jobs:
# JOB to run change detection
changes:
runs-on: ubuntu-latest
# Set job outputs to values from filter step
outputs:
deploy: ${{ steps.filter.outputs.deploy }}
steps:
- name: Checkout
uses: actions/checkout@v3
with:
fetch-depth: 0 # Fetch all history for .GitInfo and .Lastmod
- uses: dorny/paths-filter@v2
id: filter
with:
filters: |
deploy:
- 'documentations/**'
deploy:
needs: changes
if: |
${{ needs.changes.outputs.deploy == 'true' }} &&
${{ github.ref == 'refs/heads/develop' }}
runs-on: ubuntu-latest
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
steps:
- name: Checkout
uses: actions/checkout@v3
with:
submodules: true # Fetch Hugo themes (true OR recursive)
fetch-depth: 0 # Fetch all history for .GitInfo and .Lastmod
- name: Build
run: make doc-generate
- name: Deploy
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./published-documentation
incaya-documentation est sous licence Apache, avec la permission d'Incaya.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent