Documentation relative au bâtiment¶
Avant d'apporter des modifications à la documentation de BeeWare, il est utile de confirmer que vous pouvez construire la documentation existante.
Avant de créer la documentation, configurez un environnement de développement.
Vous devez avoir un interpréteur Python 3.13 installé
et disponible sur votre chemin (c'est-à-dire que python3.13 doit démarrer un interpréteur Python 3.13).
BeeWare utilise tox pour construire la documentation. Les commandes
tox suivantes doivent être lancées depuis le même emplacement que le fichier
tox.ini, qui se trouve dans le répertoire racine du projet.
Aperçu de la documentation en direct¶
Pour faciliter l'édition rapide de la documentation, BeeWare dispose d'un mode "aperçu en direct".
L'aperçu en direct s'affichera avec des avertissements !
Le service en direct est disponible pour itérer sur les mises à jour de votre
documentation. Pendant que vous mettez les choses à jour, vous pouvez introduire
un problème de balisage. Les problèmes considérés comme WARNING feront échouer
une compilation standard, cependant, le live serve est configuré pour indiquer
les avertissements dans la sortie de la console, tout en continuant à
construire. Cela vous permet d'itérer sans avoir à redémarrer la
prévisualisation en direct.
Un WARNING est différent d'un ERROR. Si vous introduisez un problème qui est
considéré comme un ERROR, le service en direct échouera et nécessitera un
redémarrage. Il ne redémarrera pas tant que le problème WARNING n'aura pas été
résolu.
Pour démarrer le serveur en direct :
(venv) $ tox -e docs-live
(venv) $ tox -e docs-live
(venv) C:\...>tox -e docs-live
Cela permet de créer la documentation, de démarrer un serveur web pour diffuser la documentation et de surveiller le système de fichiers pour détecter toute modification apportée à la source de la documentation.
Une fois le serveur démarré, vous verrez quelque chose comme ce qui suit dans la sortie de la console :
INFO - [11:18:51] Serving on http://127.0.0.1:8000/
Ouvrez un navigateur et accédez à l'URL fournie. Vous pouvez maintenant commencer à travailler sur la documentation. Si une modification est détectée, la documentation sera reconstruite et tout navigateur affichant la page modifiée sera automatiquement actualisé.
docs-live est une première étape
L'exécution de docs-live pour travailler avec le serveur live est destinée à
l'itération initiale. Vous devriez toujours lancer une compilation locale
avant de soumettre une pull request.
Construction locale¶
Une fois l'itération terminée, vous devrez procéder à une compilation locale de la documentation. Ce processus de construction est conçu pour échouer s'il y a des problèmes de balisage. Cela vous permet de rattraper tout ce que vous auriez pu manquer avec le serveur live.
Générer une version locale¶
Pour générer une version locale :
(venv) $ tox -e docs
(venv) $ tox -e docs
(venv) C:\...>tox -e docs
Le résultat de cette compilation se trouvera dans le répertoire _build à la
racine du projet.
Générer une version traduite locale¶
La documentation de BeeWare est traduite en plusieurs langues. Les mises à jour de la documentation en anglais peuvent entraîner des problèmes dans les versions en d'autres langues. Il est important de vérifier que toutes les versions fonctionnent avant de soumettre une demande de téléchargement.
Pour générer une compilation de toutes les traductions disponibles :
(venv) $ tox -e docs-all
(venv) $ tox -e docs-all
(venv) C:\...>tox -e docs-all
Le résultat de la compilation de chaque langue se trouve dans le répertoire
_build/html/<languagecode>, où <languagecode> est le code de langue à deux
ou cinq caractères associé à la langue spécifique (par exemple fr pour le
français, it pour l'italien, etc.)
Si vous trouvez un problème avec une seule version, vous pouvez lancer cette
version séparément en exécutant tox -e docs-<languagecode>. Par exemple, pour
compiler uniquement la documentation en français, lancez tox -e
docs-<languagecode> :
(venv) $ tox -e docs-fr
(venv) $ tox -e docs-fr
(venv) C:\...>tox -e docs-fr
Le résultat d'une compilation en une seule langue se trouve dans le répertoire
_build.
Linting de la documentation¶
Le processus de construction identifiera les problèmes Markdown, mais BeeWare effectue des vérifications supplémentaires pour le style et le formatage, connues sous le nom de "linting". Pour lancer les vérifications lint :
(venv) $ tox -e docs-lint
(venv) $ tox -e docs-lint
(venv) C:\...>tox -e docs-lint
Cela permettra de vérifier que la documentation ne contient pas de données :
- hyperliens morts
- mots mal orthographiés
Si une orthographe valide d'un mot est identifiée comme incorrecte, ajoutez le
mot à la liste de docs/spelling_wordlist. Cela ajoutera le mot au dictionnaire
du correcteur d'orthographe. Lorsque vous ajoutez un mot à cette liste,
n'oubliez pas :
- Nous préférons l'orthographe américaine, avec quelques libertés pour le langage familier spécifique à la programmation (par exemple, "apps") et le verbe des noms (par exemple, "scrollable").
- Toute référence à un nom de produit doit utiliser la majuscule préférée du produit. (par exemple, "macOS", "GTK", "pytest", "Pygame", "PyScript").
- Si un terme est utilisé "comme un code", il doit être cité comme un littéral
(
comme ceci) plutôt que d'être ajouté au dictionnaire.
Une fois que vous avez réussi à créer les documents, vous êtes prêt à rédiger la documentation.