Compilare il manuale con Sphinx

Questa pagina spiega come creare una copia locale del manuale di Godot utilizzando il motore di documentazione Sphinx. Questo permette di avere file HTML locali e di creare la documentazione sotto forma di un file PDF, EPUB oppure LaTeX, ad esempio.

Prima di cominciare, assicurarsi di avere:

Nota

Python 3 dovrebbe essere dotato del comando pip3. Potrebbe essere necessario scrivere python3 -m pip (Unix) o py -m pip (Windows) invece di pip3. Se entrambi gli approcci falliscono, controllare di avere pip3 installato.

  1. (Facoltativo) Configurare un ambiente virtuale. Gli ambienti virtuali prevengono potenziali conflitti tra i pacchetti Python in requirements.txt e altri pacchetti Python installati sul sistema.

    1. Crea l'ambiente virtuale:

      py -m venv godot-docs-venv

    2. Attivare l'ambiente virtuale:

      godot-docs-venv\Scripts\activate.bat

    3. (Facoltativo) Aggiornare i pacchetti preinstallati:

      py -m pip install --upgrade pip setuptools

  2. Clonare il repository della documentazione:

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

  3. Cambiare cartella e accedere al repository della documentazione:

    cd godot-docs

  4. Installa i pacchetti necessari:

    pip3 install -r requirements.txt

  5. Crea la documentazione:

    make html

    Nota

    Su Windows, tale comando eseguirà make.bat invece di GNU Make (o un'alternativa).

    In alternativa, è possibile compilare la documentazione eseguendo manualmente il programma sphinx-build:

    sphinx-build -b html ./ _build/html

La compilazione richiederà un po' di tempo poiché la cartella classes/ contiene centinaia di file. Consultare Suggerimenti per le prestazioni.

Sarà quindi possibile sfogliare la documentazione aprendo _build/html/index.html nel proprio browser web.

Gestire gli errori

Se si riscontrano errori, si può provare il seguente comando:

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

Nel caso di un MemoryError o EOFError, si può rimuovere la cartella classes/ ed eseguire nuovamente make. Ciò eliminerà i riferimenti alle classi dalla documentazione HTML finale ma manterrà intatto il resto.

Importante

Se viene cancellata la cartella classes/, non usare git add . quando si lavora su una richiesta di pull o l'intera cartella classes/ sarà rimossa al momento del commit. Consultare #3157 per maggiori dettagli.

Suggerimenti per le prestazioni

Utilizzo della RAM

La compilazione della documentazione richiede almeno 8 GB di RAM per funzionare senza swapping del disco, il che la rallenta. Se sono disponibili almeno 16 GB di RAM, è possibile velocizzare la compilazione eseguendo:

set SPHINXOPTS=-j2 && make html

È possibile usare -j auto per utilizzare tutti i thread della CPU disponibili, ma ciò può richiedere molta RAM se si hanno molti thread della CPU. Ad esempio, su un sistema con 32 thread della CPU, -j auto (che in questo caso corrisponde a -j 32) può richiedere più di 20 GB di RAM solo per Sphinx.

Specificare una lista di file

Avvertimento

Questa sezione non funzionerà su Windows, poiché il repository utilizza uno script make.bat semplificato invece del vero programma GNU Make. Se si desidera avere un terminale Linux sul proprio sistema, considera l'utilizzo del sottosistema Windows per Linux (WSL).

È possibile specificare un elenco di file da compilare, il che può velocizzare notevolmente la compilazione:

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

La lista di file si può anche fornire tramite il comando git. In questo modo è possibile ottenere automaticamente i nomi di tutti i file che sono cambiati dall'ultimo commit (per inserirli sulla stessa riga si usa sed).

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

È possibile sostituire HEAD con master per restituire tutti i file modificati dal ramo master:

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

If any images were modified, the output will contain some warnings about them, but the build will proceed correctly.