Documentazione dell'edificio¶
Prima di apportare qualsiasi modifica alla documentazione di {{ nome_formale }}, è utile confermare che si può costruire la documentazione esistente.
Prima di creare la documentazione, assicurati di avere un ambiente di sviluppo configurato.
È necessario avere un interprete Python 3.13 installato
e disponibile sul proprio percorso (cioè, python3.13 deve
avviare un interprete Python 3.13).
{{ nome_formale }} usa tox per costruire la documentazione. I seguenti comandi
di tox devono essere eseguiti dalla stessa posizione del file tox.ini, che
si trova nella directory principale del progetto.
Anteprima della documentazione in tempo reale¶
Per favorire la modifica rapida della documentazione, {{ nome_formale }} dispone di una modalità di "anteprima dal vivo".
L'anteprima live verrà generata con avvisi!
Il servizio live è disponibile per iterare gli aggiornamenti della documentazione. Mentre si aggiornano le cose, si può introdurre un problema di markup. I problemi considerati un `AVVERTIMENTO' causano il fallimento della compilazione standard; tuttavia, il servizio live è impostato per indicare gli avvertimenti nell'output della console, pur continuando la compilazione. Questo permette di iterare senza dover riavviare l'anteprima live.
Un AVVISO' è diverso da unERRORE'. Se si introduce un problema considerato un
ERRORE, il servizio live fallirà e richiederà un riavvio. Non si riavvierà
fino a quando il problema WARNING non sarà risolto.
Per avviare il server live:
(venv) $ tox -e docs-live
(venv) $ tox -e docs-live
(venv) C:\...>tox -e docs-live
Questo costruisce la documentazione, avvia un server web per servire la documentazione e controlla il file system per qualsiasi modifica alla fonte della documentazione.
Una volta avviato il server, nell'output della console si vedrà qualcosa di simile a quanto segue:
INFO - [11:18:51] Serving on http://127.0.0.1:8000/
Aprire un browser e navigare all'URL fornito. Ora si può iniziare a iterare sulla documentazione. Se viene rilevata una modifica, la documentazione viene ricostruita e qualsiasi browser che visualizza la pagina modificata viene automaticamente aggiornato.
docs-live è un passo iniziale
L'esecuzione di docs-live per lavorare con il server live è pensata per
l'iterazione iniziale. Si dovrebbe sempre eseguire una build locale prima di
inviare una richiesta di pull.
Costruzione locale¶
Una volta terminata l'iterazione, è necessario eseguire una compilazione locale della documentazione. Questo processo di creazione è progettato per fallire se ci sono problemi di markup. In questo modo è possibile individuare tutto ciò che potrebbe essere sfuggito con il server live.
Generazione di una build locale¶
Per generare una build locale:
(venv) $ tox -e docs
(venv) $ tox -e docs
(venv) C:\...>tox -e docs
L'output di questa compilazione sarà nella cartella _build nella radice del
progetto.
Generazione di una build locale tradotta¶
La documentazione di BeeWare è tradotta in più lingue. Gli aggiornamenti della documentazione in inglese possono potenzialmente causare problemi nelle build delle altre lingue. È importante verificare che tutte le build funzionino prima di inviare una richiesta di pull.
Per generare una build di tutte le traduzioni disponibili:
(venv) $ tox -e docs-all
(venv) $ tox -e docs-all
(venv) C:\...>tox -e docs-all
L'output di ogni compilazione di una lingua si trova nella directory associata
_build/html/<languagecode>, dove <languagecode> è il codice di due o cinque
caratteri associato alla lingua specifica (ad esempio, fr per il francese,
it per l'italiano, ecc.)
Se si riscontra un problema con una singola compilazione, è possibile eseguire
quella singola compilazione separatamente eseguendo tox -e
docs-<languagecode>. Per esempio, per creare solo la documentazione francese,
eseguire:
(venv) $ tox -e docs-fr
(venv) $ tox -e docs-fr
(venv) C:\...>tox -e docs-fr
L'output di una compilazione in una sola lingua si trova nella directory
_build.
Linting della documentazione¶
Il processo di compilazione identifica i problemi di Markdown, ma {{ nome_formale }} esegue alcuni controlli aggiuntivi per lo stile e la formattazione, noti come "linting". Per eseguire i controlli di lint:
(venv) $ tox -e docs-lint
(venv) $ tox -e docs-lint
(venv) C:\...>tox -e docs-lint
In questo modo si convalida che la documentazione non contiene:
- collegamenti ipertestuali morti
- parole sbagliate
Se un'ortografia valida di una parola viene identificata come errata, aggiungere
la parola all'elenco in docs/spelling_wordlist. Questo aggiungerà la parola al
dizionario del correttore ortografico. Quando si aggiunge a questo elenco,
ricordate:
- Preferiamo l'ortografia statunitense, con alcune libertà per i colloqui specifici della programmazione (ad esempio, "apps") e per i verbi dei nomi (ad esempio, "scrollable").
- Qualsiasi riferimento al nome di un prodotto deve utilizzare la capitalizzazione preferita dal prodotto stesso. (ad esempio, "macOS", "GTK", "pytest", "Pygame", "PyScript").
- Se un termine viene usato "come codice", allora dovrebbe essere citato come
letterale (
come questo) invece di essere aggiunto al dizionario.
Una volta completata con successo la creazione dei documenti, sei pronto per scrivere la documentazione.