Makina Blog

Le blog Makina-corpus

Publier une documentation VitePress sur Read The Docs


À l'origine, le site de documentation Read The Docs n'acceptait que les documentations Sphinx ou MKDocs. Depuis peu, le site laisse les mains libres pour builder sa documentation avec l'outil de son choix. Voici un exemple avec VitePress.

Sommaire

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
Une documentation Read The Docs
Un aperçu d'une documentation Read The Docs avec le thème classique

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

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
Logo de VitePress
Le logo de VitePress

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

Formations associées

Formations Front end

Formation VueJS

Toulouse Du 15 au 17 octobre 2024

Voir la formation

Formations Front end

Formation Nuxt 3

Aucune session de formation n'est prévue pour le moment.

Pour plus d'informations, n'hésitez pas à nous contacter.

Voir la formation

Actualités en lien

Image
TerraVisu démo
27/11/2023

2023 : quelles nouveautés pour TerraVisu ?

Cette année, la solution TerraVisu a connu des bouleversements, tant dans l'organisation de son code source que dans l'amélioration et l'enrichissement de ses fonctionnalités.

Voir l'article
Image
Geotrek
15/11/2023

Geotrek, 11 ans d’une communauté grandissante

Cet article présente l'organisation communautaire du logiciel libre Geotrek et met en avant quelques ingrédients, qui selon nous, permettent de fédérer et donc de participer à la réussite d'un logiciel libre.

Voir l'article
Image
Django_leaflet_GeoDjango
03/09/2013

Des cartes avec GeoDjango et Leaflet

Un guide pas à pas pour visualiser vos modèles Django avec Leaflet.

Voir l'article

Inscription à la newsletter

Nous vous avons convaincus