Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

Aggiungere documentazione

Nota

Aggiungere documentazione per le GDExtension è possibile solo con Godot 4.3 e superiori.

Il sistema di documentazione di GDExtension funziona in modo simile alla documentazione integrata del motore: utilizza file XML (uno per classe) per documentare i costruttori, le proprietà, i metodi, le costanti, i segnali e altro ancora esposti.

Per cominciare, individua la cartella del progetto di test del tuo progetto, che dovrebbe contenere un progetto Godot con l'estensione installata e funzionante. Se stai usando godot-cpp-template, il progetto GDExtension ha già una cartella project. Alternativamente, la puoi aggiungere seguendo i passaggi descritti in Per cominciare. All'interno della cartella project, esegui il seguente comando da terminale:

# Replace "godot" with the full path to a Godot editor binary
# if Godot is not installed in your `PATH`.
godot --doctool ../ --gdextension-docs

Questo comando indica a Godot di generare la documentazione tramite i comandi --doctool e --gdextension-docs. L'argomento ../ specifica il percorso base della propria GDExtension.

Dopo aver eseguito questo comando, bisognerebbe trovare i file XML delle classi GDExtension registrate nella cartella doc_classes del progetto GDExtension. Potresti modificarli ora, ma per questo tutorial i file vuoti andranno bene.

Ora che ci sono file XML contenenti la documentazione, il prossimo passo è includerli nel binario GDExtension. Supponendo che si stia usando SCons come sistema di compilazione, è possibile aggiungere le seguenti righe al file SConstruct. Se si sta usando godot-cpp-template, tale file contiene già il codice per questo.

if env["target"] in ["editor", "template_debug"]:
    doc_data = env.GodotCPPDocData("src/gen/doc_data.gen.cpp", source=Glob("doc_classes/*.xml"))
    sources.append(doc_data)

L'istruzione if impedisce di aggiungere la documentazione alle build di rilascio della propria GDExtension, dove non è necessaria. SCons poi carica tutti i file XML presenti nella cartella doc_classes e aggiunge i target risultanti all'array sources, affinché siano inclusi nella build della propria GDExtension.

Dopo la compilazione, avvia nuovamente il progetto Godot. È possibile aprire la documentazione di una delle classi di estensione premendo Ctrl + clic sul nome della classe nell'editor di script, oppure trovandola nella finestra di aiuto dell'editor. Se tutto è andato a buon fine, dovresti vedere qualcosa di simile a questo:

../../../_images/gdextension_docs_generation.webp

Scrivere e stilizzare la documentazione

Il formato dei file XML del riferimento classi è lo stesso utilizzato da Godot. È documentato in Principio di riferimento classi.

Se stai cercando suggerimenti per scrivere documentazione di alta qualità, fai riferimento alle linee guida per la documentazione di Godot.

Pubblicare online la documentazione

Potrebbe essere desiderato pubblicare un riferimento online per la propria GDExtension, simile a questo sito web. Il passaggio più importante è creare file reStructuredText (.rst) dal proprio riferimento classi in XML:

# You need a version.py file, so download it first.
curl -sSLO https://raw.githubusercontent.com/godotengine/godot/refs/heads/master/version.py

# Edit version.py according to your project before proceeding.
# Then, run the rst generator. You'll need to have Python installed for this command to work.
curl -sSL https://raw.githubusercontent.com/godotengine/godot/master/doc/tools/make_rst.py | python3 - -o "docs/classes" -l "en" doc_classes

I file .rst saranno ora disponibili in docs/classes/. Da qui, puoi utilizzare qualsiasi strumento di creazione di documentazione che supporti la sintassi reStructuredText per creare un sito web da essi.

godot-docs utilizza Sphinx. È possibile usare il repository come riferimento per costruire il proprio sistema di documentazione. La seguente guida descrive i passaggi fondamentali, ma non è esaustiva: ci sarà bisogno di un po' di intuizione personale per farlo funzionare.

  1. Aggiungi godot-docs come sotto-modulo alla tua cartella docs/.

  2. Copia i file conf.py, index.rst e .readthedocs.yaml nella cartella /docs/. In seguito, potresti decidere di copiare e modificare altri file di godot-docs, come _templates/layout.html.

  3. Modifica questi file in base al tuo progetto. Si tratta principalmente di adattare i percorsi in modo che puntino alla sottocartella godot-docs, nonché le stringhe per indicare che stai creando la documentazione per il tuo progetto e non per Godot.

  4. Crea un account su readthedocs.org. Importa il progetto e modifica il percorso del file base .readthedocs.yaml in /docs/.readthedocs.yaml.

Una volta completati tutti questi passaggi, la documentazione dovrebbe essere disponibile all'indirizzo <repo-name>.readthedocs.io.