Compiler le manuel avec Sphinx

Cette page explique comment compiler une copie locale du manuel Godot en utilisant le moteur Sphinx docs. Cela vous permet d’avoir des fichiers HTML locaux et de créer la documentation sous la forme d’un fichier PDF, EPUB ou LaTeX, par exemple.

Avant de commencer, assurez-vous que vous avez :

Note

Python 3 devrait venir avec la commande pip3. Vous devrez peut-être écrire python3 -m pip (Unix) ou py -m pip (Windows) au lieu de pip3. Si les deux approches échouent, assurez-vous que vous avez pip3 d'installé https://pip.pypa.io/en/stable/installation/.

  1. (Optionnel) Créer un environnement virtuel. Les environnements virtuels empêchent les conflits potentiels entre les packages Python dans requirements.txt et d'autres packages Python qui sont installés sur votre système.

    1. Création de l'environnement virtuel :

      py -m venv godot-docs-venv

    2. Activation de l'environnement virtuel :

      godot-docs-venv\Scripts\activate.bat

    3. (optionnel) Mise à jour des paquets pré-installés :

      py -m pip install --upgrade pip setuptools

  2. Cloner le dépôt de documents :

    git clone https://github.com/godotengine/godot-docs.git

  3. Changer de répertoire vers le dépôt de documentation :

    cd godot-docs

  4. Installation des packages requis :

    pip3 install -r requirements.txt

  5. Création des documentations :

    make html

    Note

    Sur Windows, cette commande va exécuter make.bat au lieu de GNU Make (ou une alternative).

    Autrement, vous pouvez compiler la documentation en exécutant manuellement le programme sphinx-build :

    sphinx-build -b html ./ _build/html

La compilation prendra un certain temps car le dossier classes/ contient des centaines de fichiers. Voir Indices de performance.

Vous pouvez ensuite parcourir la documentation en ouvrant _build/html/index.html dans votre navigateur web.

Traiter avec des erreurs

Si vous rencontrez des erreurs, vous pouvez essayer la commande suivante :

make SPHINXBUILD=~/.local/bin/sphinx-build html

Si vous obtenez un MemoryError ou un EOFError, vous pouvez supprimer le dossier classes/ et relancer make. Cela supprimera les références aux classes dans la documentation HTML finale mais gardera le reste intact.

Important

Si vous supprimez le dossier classes/, n'utilisez pas git add . lorsque vous travaillez sur une pull request ou l'ensemble du dossier classes/ sera supprimé lors du commit. Voir #3157 pour plus de détails.

Indices de performance

Utilisation de la RAM

La compilation de la documentation requiert au moins 8 Go de RAM pour fonctionner sans swapping, ce qui la ralentit. Si vous avez au moins 16 Go de RAM, vous pouvez accélérer la compilation en exécutant :

set SPHINXOPTS=-j2 && make html

Vous pouvez utiliser -j auto pour utiliser tous les threads CPU disponibles, mais cela peut utiliser beaucoup de RAM si vous avez beaucoup de threads CPU. Par exemple, sur un système avec 32 threads CPU, -j auto (qui correspond à -j 32 ici) peut nécessiter plus de 20 Go de RAM pour Sphinx seulement.

Spécifier une liste de fichiers

Avertissement

Cette section ne fonctionnera pas sur Windows, puisque le dépôt utilise un script simplifié make.bat au lieu du vrai programme GNU Make. Si vous souhaitez obtenir un terminal Linux sur votre système, considérez l'utilisation du Sous-système Windows pour Linux (WSL, Windows System for Linux).

Vous pouvez aussi lister des fichiers spécifiques à compiler, cela peut grandement accélérer la compilation :

make html FILELIST='classes/class_node.rst classes/class_resource.rst'

La liste des fichiers peut également être fournie par la commande git. De cette façon, vous pouvez obtenir automatiquement les noms de tous les fichiers qui ont changé depuis le dernier commit (sed est utilisé pour les mettre sur la même ligne).

make html FILELIST="$(git diff HEAD --name-only | sed -z 's/\n/ /g')"

Vous pouvez remplacer HEAD par master pour renvoyer tous les fichiers modifiés de la branche master :

make html FILELIST="$(git diff master --name-only | sed -z 's/\n/ /g')"

Si des images ont été modifiées, la sortie contiendra quelques avertissements à leur sujet, mais la compilation continuera correctement.