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 :
Clonez le dépôt godot-docs.
Installer Sphinx
Pour construire les docs en tant que fichiers HTML, installez le thème readthedocs.org.
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.