Pour qui

Passer la doc en Markdown sans nettoyage

Migrer une documentation consiste d’ordinaire à convertir du HTML, puis à passer plus longtemps encore à retirer ce que le convertisseur a gardé. C’est ce retrait qui a été construit et mesuré ici : zéro reste de balise HTML sur les 512 pages du corpus, et 102 lignes de navigation répétées contre 282, 478 et 491 pour les moteurs comparés.

La conversion n’est pas le travail

La partie facile d’une migration est celle que tout le monde regarde. Le convertisseur produit du Markdown en quelques secondes, et le vrai travail commence après : retirer la barre latérale recopiée dans chaque fichier, le sélecteur de version, le fil « Sur cette page », le pied de page et ses liens légaux. Sur deux cents pages, cela ne se fait ni à la main ni entièrement en expressions régulières.

Et la structure ne s’en sort pas indemne. Les titres vides laissés par les blocs de navigation créent des sections fantômes dans la table des matières, les admonitions perdent leur sens, les blocs de code perdent leur langage et les tableaux de paramètres se replient. La documentation importée est là, mais elle demande une relecture page par page avant de servir à quoi que ce soit.

La troisième difficulté n’apparaît qu’au deuxième passage : une migration n’est jamais un événement unique. La source continue de vivre, une dizaine de pages sont corrigées le mois suivant, et il faut les reprendre. Sans convention de nom stable, la reprise crée des doublons que personne ne repère ; avec un modèle fondé sur {title}, elle réécrit le fichier existant, ce qui est le comportement voulu à condition de le savoir. Fixer le modèle de nom avant la première page coûte deux minutes, et l’ignorer coûte une relecture complète.

Ce que la migration récupère

• Titres, listes, tableaux, blocs de code et notes deviennent du Markdown standard
• Les étiquettes de langage sont conservées sur les blocs de code – 73 blocs sur 156 contre 20 et 0
• Un bloc contenant lui-même trois accents graves est clôturé par quatre : la clôture ne se referme pas au mauvais endroit
• Zéro reste de balise HTML sur les 512 pages mesurées
• Barres de navigation, sélecteurs de version et fils « Sur cette page » sont coupés, pas convertis
• Les titres vides, artefact courant des blocs de navigation, sont supprimés
• Les liens relatifs deviennent absolus, donc réécrivables en une seule passe de recherche-remplacement
• Modèle de nom de fichier et sous-dossier gardent un ensemble importé en ordre

---
title: "pathlib – Chemins de système de fichiers orientés objet"
source: "https://docs.python.org/fr/3/library/pathlib.html"
extraction: "dom"
---

## Utilisation de base

```python
from pathlib import Path

for fichier in Path(".").glob("**/*.md"):
    print(fichier)
```

> Note : la classe `Path` choisit l’implémentation adaptée au système.

Préparer une reprise de documentation

Ce qui suit se règle avant la première page, pas après la cinquantième. Le point décisif est le modèle de nom : c’est lui qui rend la reprise possible dans six mois.

1. Dans les paramètres, section « Où enregistrer », désignez avec « Choisir… » le dossier de destination – celui du dépôt, ou un dossier de travail que vous y verserez ensuite. L’autorisation est demandée une fois et retenue par le navigateur.
2. Réglez « Nom du fichier » sur {title}. Dans une documentation, les titres de page sont uniques par construction, et ce modèle produit des noms proches de ceux du site d’origine. Sachez seulement que le nom est coupé à 90 caractères et que tout caractère hors lettres, chiffres, espaces et . , ( ) _ - devient un tiret.
3. Mettez la section de la documentation dans « Sous-dossier des téléchargements », et changez-le en passant à la section suivante. C’est ce qui reconstitue une arborescence lisible, puisque l’extension ne reproduit pas celle du site.
4. Passez « Images » sur « ignorer » et laissez cochées les cases « Renvoyer les notes de bas de page à la fin » et « Couper la navigation, la pagination et les blocs de service ». Les images ne sont de toute façon pas téléchargées : leurs liens pointeraient vers un site que votre dépôt ne contrôle pas.
5. Réglez « Clic sur l’icône » sur « Placer dans un dossier ». Une reprise de documentation se fait au rythme d’une page toutes les quelques secondes : Alt+Shift+M enregistre sans même ouvrir la fenêtre, ce qui laisse les deux mains sur le clavier.
6. Faites une passe d’essai sur trois pages représentatives – une page à onglets, une page avec un grand tableau de paramètres, une page avec des encarts – avant de lancer la reprise. Ce sont les trois formes qui demandent une intervention manuelle, et il vaut mieux en connaître le coût à l’avance.

Réglages conseillés pour une reprise

Ces valeurs visent un ensemble de fichiers homogène, prêt pour une relecture globale plutôt que page par page. Deux d’entre elles diffèrent de l’installation d’origine.

## Monter une partition au démarrage

> **Note** : une erreur dans ce fichier empêche le démarrage du système.

| Champ | Valeur | Rôle |
| --- | --- | --- |
| `UUID` | identifiant du volume | survit à un changement d’ordre des disques |
| `dump` | `0` | sauvegarde par l’outil historique, inutilisée aujourd’hui |

```bash
sudo blkid /dev/sda1
sudo nano /etc/fstab
```

Trois usages réels

Verser une documentation externe dans un dépôt

Un fournisseur publie sa documentation en ligne et votre équipe la veut à côté du code, en Markdown, versionnée. Vous parcourez les pages une par une avec le modèle de nom et le sous-dossier réglés une fois : chaque fichier arrive nommé de la même façon, sans barre latérale, avec ses blocs de code étiquetés.

La relecture qui suit porte sur des points identifiés à l’avance, pas sur du nettoyage. Les liens internes sont restés absolus vers le site d’origine : une passe de recherche-remplacement les convertit vers vos chemins. L’extension ne reconstruit ni la table des matières ni la navigation – cette part revient à votre générateur de site.

Rapatrier une documentation qui va fermer

Un produit est arrêté, sa documentation restera en ligne quelques mois. Vous capturez les pages qui concernent vos intégrations, avec les images ignorées puisqu’elles disparaîtront avec le site. Le texte, les tableaux de paramètres et les exemples de code sont sauvés ; les schémas, non.

Il faut le savoir avant plutôt qu’après : aucun fichier binaire n’est téléchargé, jamais. Si les schémas comptent, enregistrez-les séparément pendant que le site répond encore. C’est le même principe pour les PDF joints, qui ne sont ni suivis ni convertis.

Reprendre les pages modifiées trois mois plus tard

La source a bougé sur une dizaine de pages. Vous les recapturez avec exactement les mêmes réglages : comme le modèle de nom est fondé sur {title}, chaque fichier reprend la place de l’ancien dans le dossier, et votre système de versions vous montre précisément ce qui a changé.

C’est le comportement voulu ici : dans un dossier ou un coffre, un nom déjà pris reçoit un suffixe et rien n’est perdu sans avertissement. Si vous préférez comparer avant d’écraser, changez le sous-dossier pour la seconde passe et faites la comparaison entre les deux dossiers.

Comparé aux façons de faire actuelles

Une reprise de documentation se fait rarement de zéro. Voici les outils habituels et ce qu’ils demandent en travail humain une fois la conversion terminée.

Ce qui demande une reprise à la main

Pourquoi les liens internes de la documentation ne fonctionnent-ils plus ?

Parce qu’ils pointent toujours vers le site d’origine. Les adresses relatives sont converties en adresses absolues avant la conversion, sans quoi elles seraient irrécupérables ; elles restent donc valides tant que le site vit, mais elles ne mènent pas aux fichiers de votre dépôt.

La conversion vers vos propres chemins se fait en une passe de recherche-remplacement sur le dossier, précisément parce que toutes les adresses partagent le même préfixe. Les ancres internes à une page, elles, restent écrites #ma-section mais les identifiants correspondants ne sont pas conservés : ces liens-là sont à revoir un par un.

Pourquoi le nom du fichier est-il tronqué ?

Parce qu’il est coupé à 90 caractères. Certaines pages de documentation portent des titres longs qui incluent le nom du produit, la version et la section ; au-delà de la limite, la fin est retirée, ce qui peut rendre deux pages homonymes dans le dossier – et la seconde capture écrase alors la première.

Le titre complet reste écrit dans le champ title du frontmatter. Quand une documentation a des titres longs et proches, préférez un modèle {domain} - {title} avec un sous-dossier par section, ce qui déplace la distinction du nom vers l’arborescence.

Pourquoi l’encart « Attention » est-il devenu une citation ?

Parce que Markdown n’a pas de syntaxe standard pour les admonitions. Chaque générateur de site a la sienne, et inventer une forme reviendrait à choisir pour vous : le contenu de l’encart est donc gardé sous forme de citation, avec son texte intact et son éventuel bloc de code.

La conversion vers la syntaxe de votre générateur se scripte facilement, puisque toutes les admonitions ont pris la même forme. C’est justement pourquoi le choix a été de tout ramener à une forme unique plutôt que d’essayer de deviner le type de chaque encart.

Pourquoi la page à onglets ne contient-elle qu’un seul exemple ?

Parce que les autres onglets ne sont pas dans la page. Une documentation qui présente le même exemple en plusieurs langages construit souvent les onglets inactifs au moment du clic : ce qui n’est pas affiché n’existe pas dans le document, et rien n’est demandé au serveur pendant la capture.

Capturez une fois par onglet et rassemblez ensuite, ou choisissez l’onglet qui correspond à votre pile avant de capturer. Le même raisonnement vaut pour les sections repliées et les exemples chargés à la demande.

Ce qu’il ne fait pas

Il n’explore pas un site : une page à la fois, celle que vous regardez, sans robot et sans traitement par lots – une documentation de deux cents pages demande deux cents captures. Il ne télécharge pas les images ni les schémas, qui restent des liens vers le site d’origine. Les encarts et admonitions deviennent des citations, parce que Markdown n’a pas de syntaxe standard pour eux : le contenu est gardé, le style non. Et il ne reconstruit ni les liens internes de la documentation ni sa table des matières.

Questions