Use MkDocs for documentation

[imperosol]

Migration de Sphinx vers mkdocs, avec réécriture et réorganisation d'une bonne partie en passant.

Ca inclut :

• passage de rst à markdown pour la rédaction de la doc
• Retour du déploiement automatique de la doc, en utilisant les github pages pour ça
• Un thème plutôt pas dégueu
• Configuration plus simple
• Déplacement des PDFs sur le Wiki GitHub avec un lien depuis la doc pour alléger le repo
• Ajouts de nouveaux rapports

[Juknum]

Hello,

Pourquoi ne pas simplement utiliser le wiki du repo pour la doc? Avec @TheoDurr on s'était dit que ça serait plus simple a mettre en place plutôt que devoir gérer un truc en plus...

[klmp200]

Hello,

Pourquoi ne pas simplement utiliser le wiki du repo pour la doc? Avec @TheoDurr on s'était dit que ça serait plus simple a mettre en place plutôt que devoir gérer un truc en plus...

Les requirements pour la documentation sont les suivants :

• Être près du code
  • Permet d'avoir la documentation rapidement sans avoir à aller sur internet, tout est dans le repo
  • Réduit la friction pour la mettre à jour puisqu'elle est proche du code
  • Permet de râler dans une PR quand la documentation n'a pas été update
  • Permet de versionner la documentation pour qu'elle soit toujours synchronisée avec le code
• Avoir des parties auto-généres à partir du code lui même
• Ne pas être dépendant d'un service

Le problème de mettre ça dans le wiki de github c'est que c'est loin du code et ça pose soucis. En plus, c'est un autre set de droits à attribuer à certains développeurs et ça rajoute de la friction
De plus, on perd tout versionnage et le code se désynchro de la doc.
Et enfin, avoir des parties générés à partir du code et même faire référence dans la documentation à ces parties générées ça nécessite de développer un tooling spéciale et une sorte de synchronisation qui rend l'affaire très complexe.
D'ailleurs, si on commence à développer quelque chose comme ça, on deviens dépendant du wiki github et de son API !

La solution ici est de générer la documentation et de la publier sur github pages, ce qui en soit ne rajoute pas vraiment un autre service puisque c'est fourni par github. Et ça permet d'utiliser des logiciels de génération de documentation qui sont bien plus robustes que toute solution qu'on fabriquerait. Et puisque c'est une documentation qui peut se générer en local, on a pas vraiment de dépendance avec le service où on publie la documentation, c'est juste un côté pratique pour les utilisateurs qui débutent sur le projet ou qui ont rapidement besoin de vérifier un truc sans build en local.

[klmp200]

Pour moi c'est bon