Nous avons tous déjà lu une documentation publiée sur Read The Docs, c'est par exemple le cas des documentations de Flask ou Jupyter. Ce site bien connu des développeurs rend facilement accessible au plus grand nombre la documentation d'un produit ou bien d'une bibliothèque.

Image

Chez Makina, nous aimons bien l'utiliser pour nos projets open source, nous y avons par exemple publié les documentations de :

• django-geostore
• django-leaflet
• Geotrek
• TerraVisu
• DbToolsBundle
• php-query-builder

Le site permettait à l'origine de publier des documentations écrites seulement en Sphinx ou MKDocs. Mais depuis mai dernier, ReadTheDocs laisse la possibilité, en version beta, d'écrire à la main l'étape de génération de la documentation. Il est alors possible d'utiliser le système de génération de documentation de son choix, pour peu que celui-ci retourne des fichiers HTML statiques.

Image

Dans le monde des générateurs de documentation, j'aime beaucoup VitePress. Cet outil est notamment utilisé pour générer la documentation de Vue.js. Sa présentation est claire et la navigation est agréable. L'outil est aussi très simple à mettre en place et à utiliser en tant que rédacteur.

Publier une documentation en VitePress sur Read The Docs

Création de la documentation VitePress

À la racine du dépôt Git de votre projet, créez un dossier "docs" et rendez-vous y :

mkdir docs
cd docs

C'est dans ce dossier que vivra votre documentation. Créez-y un fichier "package.json" contenant :

{
  "scripts": {
    "docs:dev": "vitepress dev",
    "docs:build": "vitepress build",
    "docs:preview": "vitepress preview"
  },
  "type": "module",
  "devDependencies": {
    "vitepress": "^1.0.0-beta.6"
  }
}

Puis lancez :

npm install

À cet étape, vous pouvez voir à quoi ressemble votre documentation en lançant :

npm run docs:dev

Pour rendre votre documentation compatible avec Read The Docs, vous devez :

• Respecter la notion du Public Directory pour vos images (mais cela reste vrai dans tout les cas)
• Désactiver les Clean Urls qui ne fonctionnent pas avec Read The Docs

Je vous conseille également d'ajouter ce fichier ".gitignore" dans le dossier docs :

.vitepress/cache/
.vitepress/dist/
node_modules/

Vous pouvez maintenant commiter votre documentation :

cd ..
git add docs
git commit -m "Initialize documentation"

Paramétrage de Read The Docs

La paramétrage d'une documentation Read The Docs se fait en plaçant un fichier ".readthedocs.yaml" à la racine de votre projet. Voici le contenu que celui-ci doit avoir dans le cas d'une documentation VitePress :

# Read the Docs configuration file for Sphinx projects
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details

# Required
version: 2

# Set the OS, Python version and other tools you might need
build:
  os: ubuntu-22.04
  tools:
    nodejs: "18"
  commands:
    - mkdir --parents $READTHEDOCS_OUTPUT/html/
    - cd docs && npm ci
    - cd docs && npm run docs:build -- --base "/$READTHEDOCS_LANGUAGE/$READTHEDOCS_VERSION/"
    - cp --recursive docs/.vitepress/dist/* $READTHEDOCS_OUTPUT/html/

Nous ajoutons ce fichier à notre dépôt Git :

git add .readthedocs.yaml
git commit -m "Add readthedocs configuration"

git push

Notre dépôt est maintenant prêt à être intégré à Read The Docs. Ici, pas de difficulté, il suffit de suivre les indications de l'outil d'import du site.

Et voilà ce que cela donne avec notre exemple : publier une documentation en VitePress sur Read The Docs.

Pour aller plus loin

• Retrouvez cet exemple de documentation sur ce dépôt Github
• Lisez la référence complète de l'étape du build de Read The Docs sur leur documentation
• Allez voir la documentation de VitePress