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.

Pour commencer, vous devez :

  1. Clonez le dépôt godot-docs.

  2. Installer Sphinx

  3. Pour construire les docs en tant que fichiers HTML, installez le thème readthedocs.org.

  4. Installez les extensions Sphinx définies dans le fichier godot-docs repository requirements.txt.

Nous recommandons d'utiliser pip, le gestionnaire de paquets de Python pour installer tous ces outils. Il est livré préinstallé avec Python. Assurez-vous que vous installez et utilisez Python 3. Voici les commandes pour cloner le dépôt et ensuite installer toutes les exigences.

Note

Vous devrez peut-être écrire python3 -m pip (Unix) ou py -m pip (Windows) au lieu de pip3. Si les deux approches échouent, vérifiez que vous avez pip3 installé.

git clone https://github.com/godotengine/godot-docs.git
pip3 install -r requirements.txt

Avec les programmes installés, vous pouvez compiler la documentation HTML depuis le répertoire racine avec la commande suivante :

# On Linux and macOS
make html

# On Windows, you need to execute the ``make.bat`` file instead.
make.bat html

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

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

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 :

# On Linux/macOS
make html SPHINXOPTS=-j2

# On Windows
set SPHINXOPTS=-j2 && make html

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

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

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.

Note

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.

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

sphinx-build -b html ./ _build

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

sphinx-build -b html ./ _build classes/class_node.rst classes/class_resource.rst

Compilation avec Sphinx et virtualenv

Si vous voulez que votre installation de Sphinx soit appliqué au projet, vous pouvez installer sphinx-build en utilisant virtualenv. Pour le faire, exécutez cette commande depuis le répertoire racine :

virtualenv --system-site-packages env/
. env/bin/activate
pip3 install -r requirements.txt

Ensuite, exécutez make html comme indiqué ci-dessus.