Up to date

This page is up to date for Godot 4.3. If you still find outdated information, please open an issue.

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.

Before you get started, make sure that you have:

Note

Python 3 should come with the pip3 command. You may need to write python3 -m pip (Unix) or py -m pip (Windows) instead of pip3. If both approaches fail, make sure that you have pip3 installed.

  1. (Optional) Set up a virtual environment. Virtual environments prevent potential conflicts between the Python packages in requirements.txt and other Python packages that are installed on your system.

    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. Change directory into the docs repo:

    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

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

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