Contribuire alla documentazione

Questa guida spiega come contribuire alla documentazione di Godot, che sia scrivendo o revisionando pagine.

Vedi anche

Se si desidera tradurre le pagine o il riferimento alle classi dall'inglese ad altre lingue, leggere Localizzazione dell'editor e della documentazione.

Per iniziare

Per modificare o creare pagine nel manuale di riferimento, è necessario modificare i file .rst nel repository godot-docs su GitHub. Modificare queste pagine in una richiesta di pull attiva una ricostruzione della documentazione online al momento del merge.

Vedi anche

Per dettagli sull'utilizzo di Git e sul flusso di lavoro delle richieste di pull, consultare la pagina Pull request workflow. Gran parte di quanto descritto per il repository principale godotengine/godot è valido anche per il repository della documentazione.

Avvertimento

I file sorgente del riferimento alle classi si trovano nel repository del motore Godot. Da questi, generiamo la sezione Riferimento alle classi di questa documentazione. Per aggiornare la descrizione di una classe, i suoi metodi o le sue proprietà, leggere Contribuire al riferimento classi.

Cos'è la documentazione di Godot

The Godot documentation is intended as a comprehensive reference manual for the Godot game engine. It is not meant to contain step-by-step tutorials, except for two game creation tutorials in the Getting Started section.

Ci sforziamo a scrivere contenuti concreti in un linguaggio accessibile e ben scritto. Per contribuire, consigliamo di leggere anche:

Linee guida di scrittura. Qui si troveranno regole e raccomandazioni per scrivere in modo che tutti possano comprendere.
Linee guida sul contenuto. Descrivono i principi che seguiamo per scrivere la documentazione e il tipo di contenuto che accettiamo.

Contribuire cambiamenti

Le richieste di pull dovrebbero normalmente utilizzare il branch master. Invia richieste di pull ad altri branch (ad esempio 3.6 o 4.2) solamente se le modifiche si applicano solo a quella specifica versione di Godot. Dopo che una richiesta di pull è stata unita a master, verrà solitamente selezionata nel branch stabile attuale dai responsabili della documentazione.

Sebbene meno comodo da modificare rispetto a un wiki, questo repository Git è dove scriviamo la documentazione. Avere accesso diretto ai file sorgente tramite un sistema di controllo versioni è buono per garantire la qualità della nostra documentazione.

Modificare le pagine esistenti

Per modificare una pagina esistente, individuare il suo file sorgente .rst e aprirlo con un editor di testo a scelta. Sarà quindi possibile eseguire il commit delle modifiche, inviarle al proprio fork ed effettuare una richiesta di pull. Nota che le pagine in classes/ non si devono modificare qui. Vengono generate automaticamente dal riferimento alle classi XML di Godot. Consultare Contribuire al riferimento classi per i dettagli.

Vedi anche

Per compilare il manuale e testare le modifiche sul proprio computer, consultare Compilare il manuale con Sphinx.

Modificare le pagine online

È possibile modificare la documentazione online cliccando sul collegamento Modifica su GitHub in alto a destra di ogni pagina.

In questo modo si accede all'editor di testo di GitHub. Per utilizzarlo, è necessario avere un account GitHub e aver effettuato l'accesso. Una volta effettuato l'accesso, è possibile proporre modifiche in questo modo:

Cliccare sul pulsante Modifica su GitHub.
Nella pagina GitHub a cui si verrà indirizzati, assicurarsi che il branch attuale sia "master". Cliccare sull'icona della matita nell'angolo in alto a destra, vicino ai pulsanti Raw, Blame ed Delete. Ha un suggerimento "Fork this project and edit the file".
Modifica il testo nell'editor di testo.
Cliccare su "Commit changes...", riepilogare le modifiche apportate e assicurarsi di sostituire il segnaposto "Update file.rst" con una breve ma chiara descrizione di una sola riga, poiché questo è il titolo del commit. Cliccare sul pulsante Propose changes.
Nelle schermate successive, cliccare sul pulsante Create pull request finché non appare un messaggio simile a Username wants to merge 1 commit into godotengine:master from Username:patch-1.

Nota

Se nella richiesta di pull sono presenti più commit del proprio, è probabile che il proprio branch sia stato creato utilizzando l'origine sbagliata, perché "master" non era il branch attuale nel passaggio 2. Sarà necessario riassegnare il branch a "master" o crearne uno nuovo.

Un altro collaboratore esaminerà le tue modifiche e, se sono valide, effettuerà il merge sulla documentazione. Potrebbe anche apportare modifiche o chiedere di farlo prima di ciò.

Aggiungere nuove pagine

Prima di aggiungere una nuova pagina, assicurarsi che sia compatibile con la documentazione esistente:

Cercare problemi esistenti oppure aprirne uno nuovo per vedere se la pagina è necessaria.
Assicurarsi che non ci sia già una pagina che tratta l'argomento.
Leggere le nostre Linee guida sul contenuto.

Per aggiungere una nuova pagina, creare un file .rst con un nome significativo nella sezione a cui si vuole aggiungere il file, ad esempio tutorials/3d/light_baking.rst.

Si dovrebbe quindi aggiungere la propria pagina al "toctree" pertinente (tabella di contenuti, ad esempio tutorials/3d/index.rst). Aggiungere il nuovo nome file all'elenco su una nuova riga, utilizzando un percorso relativo e nessuna estensione, ad esempio in questo caso light_baking.

Titoli

Cominciare sempre le pagine con il titolo e un nome di riferimento per Sphinx:

.. _doc_insert_your_title_here:

Insert your title here
======================

Il riferimento _doc_insert_your_title_here e il titolo devono corrispondere.

The reference allows linking to this page using the :ref: format, e.g. :ref:`doc_insert_your_title_here` would link to the above example page (note the lack of leading underscore in the reference).

Scrivere i titoli come frasi semplici, senza mettere in maiuscolo ogni parola:

Buono: Comprendere i segnali in Godot
Sbagliato: Comprendere I Segnali In Godot

Solo i nomi propri, i progetti, le persone e i nomi delle classi di nodi devono avere la prima lettera maiuscola.

Sintassi di Sphinx e reStructuredText

Consultare reST Primer di Sphinx e il riferimento ufficiale per i dettagli sulla sintassi.

Sphinx utilizza commenti reST specifici per effettuare operazioni specifiche, come la definizione della tabella dei contenuti (.. toctree::) o il riferimento incrociato alle pagine. Consultare la documentazione ufficiale di Sphinx per ulteriori dettagli. Per imparare a utilizzare le direttive di Sphinx come .. note:: o .. seealso::, consultare la documentazione sulle direttive di Sphinx.

Aggiungere immagini e allegati

Per aggiungere immagini, inserirle nella cartella img/ accanto al file .rst con un nome significativo e includerle nella propria pagina con:

.. image:: img/image_name.webp

In alternativa, è possibile utilizzare la direttiva figure, che fornisce all'immagine un bordo contrastante e consente di centrarla sulla pagina.

.. figure:: img/image_name.webp
    :align: center

È anche possibile includere allegati come materiale di supporto per un tutorial, inserendoli nella cartella files/ accanto al file .rst e utilizzando questo markup in riga:

:download:`file_name.zip <files/file_name.zip>`

Si consiglia di utilizzare il repository godot-docs-project-starters <https://github.com/godotengine/godot-docs-project-starters> per ospitare materiali di supporto, come modelli di progetto e pacchetti di contenuti. Si può utilizzare un collegamento diretto all'archivio generato da quel repository con il normale markup di collegamento:

`file_name.zip <https://github.com/godotengine/godot-docs-project-starters/releases/download/latest-4.x/file_name.zip>`_

Licenza

Questa documentazione e ogni pagina in essa contenuta è pubblicata sotto i termini della licenza Creative Commons Attribution 3.0 (CC-BY-3.0), con attribuzione a "Juan Linietsky, Ariel Manzur e la comunità Godot".

Contribuendo alla documentazione sul repository di GitHub, si accetta che le proprie modifiche siano distribuite sotto questa licenza.