Code Monkey home page Code Monkey logo

incaya-documentation's Introduction

Incaya Documentation

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.

Le site de documentation vide

Principe de fonctionnement

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.

Utilisation avec Docker

Il existe deux versions de l'image docker : une avec des contenus en français ghcr.io/incaya/incaya-documentation:fr et l'autre en anglais ghcr.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.md

La présence des répertoires adrs et docs correspond à 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:fr

Hugo 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# exit

Le site de documentation est alors visible sur http://localhost:1313

Excalidraw est accessible sur http://localhost:3000

Utilisation avec Docker Compose

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:1313

Et 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 \
	'

Générer des documents

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 \
	'

Surchager la configuration

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:3000

Publication

Si 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

Mainteneur

alexisjanvier Alexis Janvier

License

incaya-documentation est sous licence Apache, avec la permission d'Incaya.

incaya-documentation's People

Contributors

alexisjanvier avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar

incaya-documentation's Issues

Gestion explicite des dates

Afficher la date de création des articles, la date de mise à jour et le différentiel entre les deux. Ceci afin de rendre explicite l'age de l'article ! Éventuellement, ajouter un flag pour activer ou désactiver cette feature.

Reprendre le template

Remonter le template à la racine pour ne plus dépendre d'un théme.
Améliorer l'existant pour le rendre plus configurable (exemple : le lien incaya en bas de page, un lien Github, etc ...)

Doublon des illustrations

Pour le moment, il faut doublonner les fichiers images déclarés dans le markdown, afin qu'ils soient lisible aussi bien depuis le fichier .md sur Github que par la version html de hugo.
Par exemple, pour un article documentation/docs/architecture.md avec

---
title: Architecture in a nutshell
slug: architecture-in-a-nutshell
weight: 2
date: 2022-09-05T13:39:10Z
draft: false
summary: "A diagram summarizing the overall architecture of the project"
---

![Architecture](archi.png)

il faudra les deux fichiers documentation/docs/archi.png et documentation/docs/architecture-in-a-nutshell/archi.png

Voir comment on peut éviter cela.

Faire des images par locale

Pour simplifier l'utilisation en français et en anglais, et puisque la solution de l'internationalisation n'est pas retenue pour le moment (faute de besoin), générer deux images taggée en :fr et :en.

Ajouter un option langue fr ou en

Ajouter une option (sous quelle forme) permettant de déclarer la doc en anglais ou en français. Selon le choix, le template des nouveaux ADR serait en anglais ou en français, et l'url de la recherche en /search ou /recherche.

Fix Excalidraw

Excalidraw ne fonctionne plus depuis le passage à pnpm

documentation_1      | yarn run v1.22.19
documentation_1      | warning Skipping preferred cache folder "/.cache/yarn" because it is not writable.
documentation_1      | warning Selected the next writable cache folder in the list, will be "/tmp/.yarn-cache-1001".
documentation_1      | $ react-scripts start
documentation_1      | warning Cannot find a suitable global folder. Tried these: "/usr/local, /.yarn"
documentation_1      | WARN 2022/10/21 09:21:20 found no layout file for "JSON" for layout "search" for kind "section": You should create a template file which matches Hugo Layouts Lookup Rules for this combination.



documentation_1      | ./src/components/LibraryMenuItems.tsx
documentation_1      | Module not found: Can't resolve 'lodash' in '/excalidraw/src/components'
documentation_1      | Compiling...
documentation_1      | Failed to compile.
documentation_1      | 
documentation_1      | ./src/components/LibraryMenuItems.tsx
documentation_1      | Module not found: Can't resolve 'lodash' in '/excalidraw/src/components'
documentation_1      | Compiling...
documentation_1      | Failed to compile.
documentation_1      | 
documentation_1      | ./src/components/LibraryMenuItems.tsx
documentation_1      | Module not found: Can't resolve 'lodash' in '/excalidraw/src/components'

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.