Cosa leggere dopo¶
Quindi hai letto tutto il materiale introduttivo e hai deciso di continuare a usare Django. Abbiamo appena scalfito la superficie con questa introduzione (infatti, se hai letto ogni singola parola, hai letto circa il 5% della documentazione complessiva).
Quindi, qual è il prossimo?
Bene, siamo sempre stati grandi fan dell’imparare facendo. A questo punto dovresti sapere abbastanza per iniziare un tuo progetto e iniziare a sperimentare. Quando avrai bisogno di imparare nuovi trucchi, torna nella documentazione.
Ci siamo impegnati molto per rendere la documentazione di Django utile, chiara ed il più completa possibile. Il resto di questo documento spiega di più su come funziona la documentazione in modo che tu possa ottenere il massimo da essa.
(Sì, questa è documentazione sulla documentazione. Puoi essere certo che non abbiamo intenzione di scrivere un documento su come leggere il documento sulla documentazione.)
Trovare la documentazione¶
Django ha molta documentazione - quasi 450.000 parole e il conteggio - quindi trovare ciò di cui hai bisogno a volte può essere complicato. Un buon punto di partenza è: Indice. Si consiglia inoltre di utilizzare la funzione di ricerca incorporata.
O puoi semplicemente curiosare!
Com’è organizzata la documentazione¶
La documentazione principale di Django è suddivisa in «blocchi» progettati per soddisfare diverse esigenze:
Il materiale introduttivo è ideato per persone che siano nuove con Django – o allo sviluppo web in generale. Non copre niente nel dettaglio ma dà invece una overview di alto livello su come è sviluppare con Django.
Le topic guides, d’altra parte, approfondiscono le singole parti di Django. Ci sono guide complete a Django model system, template engine, forms framework e molto altro.
Probabilmente è qui che vorrai trascorrere la maggior parte del tuo tempo; se ti fai strada attraverso queste guide dovresti uscire sapendo praticamente tutto quello che c’è da sapere su Django.
Lo sviluppo Web è spesso ampio, non profondo: i problemi riguardano molti ambiti. Abbiamo scritto una serie di guide pratiche che rispondono alle comuni domande «Come faccio a …?». Qui troverai informazioni sulla generazione di PDF con Django, scrittura di template tag personalizzati, e altro.
Le risposte a domande molto comuni possono essere trovate anche nelle FAQ.
Le guide e le istruzioni non coprono ogni singola classe, funzione e metodo disponibile in Django – sarebbe eccessivo quando stai cercando di imparare. Invece, i dettagli su singole classi, funzioni, metodi e moduli sono conservati in reference. Qui è dove ti dirigerai per trovare i dettagli di una particolare funzione o qualsiasi cosa tu abbia bisogno.
Se sei interessato a distribuire un progetto pubblicamente, la nostra documentazione contiene diverse guide per vari tipi di distribuzione, nonché una lista di controllo con alcune cose a cui dovrai pensare per la distribuzione.
Infine, c’è una documentazione «specialized» di solito non rilevante per la maggior parte degli sviluppatori. Ciò include release notes e internals documentation per coloro che vogliono aggiungere codice a Django stesso, e un :doc:` altre cose che non potevano andare altrove </misc/index>`.
Com’è aggiornata la documentazione¶
Proprio come la code base di Django viene sviluppata e migliorata quotidianamente, la nostra documentazione migliora costantemente. Miglioriamo la documentazione per diversi motivi:
- Per sistemare il contenuto, come la grammatica o errori di battitura.
- Aggiungere informazioni e/o esempi alle sezioni già esistenti che hanno bisogni di essere estese.
- Documentare le features di Django che non sono ancora state documentate. ( La lista di tale features si restringe, ma è comunque presente.)
- Per aggiungere la documentazione per nuove funzionalità man mano che vengono aggiunte, o quando cambiano le API o alcuni comportamenti di Django.
La documentazione di Django è conservata nello stesso sistema di controllo del codice sorgente del suo codice. Si trova nella directory docs del nostro repository Git. Ogni documento online è un file di testo separato nel repository.
Dove trovarla¶
Puoi leggere la documentazione Django in diversi modi. Questi, in ordine di preferenza:
Sul web¶
La versione più recente della documentazione di Django è disponibile su https://docs.djangoproject.com/en/dev/. Queste pagine HTML vengono generate automaticamente dai file di testo del codice sorgente. Ciò significa che riflettono le «ultime e migliori» di Django - includono le ultime correzioni e aggiunte, e discutono le ultime funzionalità di Django, che potrebbero essere disponibili solo per gli utenti della versione di sviluppo di Django. (Vedi: ref:differences-between-doc-versions di seguito.)
Ti incoraggiamo ad aiutare a migliorare i documenti inviando modifiche, correzioni e suggerimenti nel ticket system. Gli sviluppatori di Django monitorano attivamente il ticket system e usano il tuo feedback per migliorare la documentazione per tutti.
Nota, tuttavia, che i ticket dovrebbero riferirsi esplicitamente alla documentazione, piuttosto che porre domande generali di supporto tecnico. Se hai bisogno di aiuto con la tua particolare configurazione Django, prova | django-users | mailing list oppure il canale #django su IRC.
In testo semplice¶
Per lettura offline, o anche solo per convenienza, puoi leggere la documentazione di Django in testo semplice.
Se stai usando una versione ufficiale di Django, il pacchetto zippato (tarball) del codice include una directory docs/, che contiene tutta la documentazione per quella versione.
Se stai utilizzando la versione di sviluppo di Django (ovvero il ramo principale), la directory docs/ contiene tutta la documentazione. Puoi aggiornare Git per ottenere le ultime modifiche.
Un modo a bassa tecnologia per trarre vantaggio dalla documentazione di testo è usare l’utility grep di Unix per cercare una frase in tutta la documentazione. Ad esempio, questo ti mostrerà ogni menzione della frase «max_length» in qualsiasi documento Django:
$ grep -r max_length /path/to/django/docs/
...\> grep -r max_length \path\to\django\docs\
Come HTML, in locale¶
È possibile ottenere una copia locale della documentazione HTML seguendo semplici passaggi:
La documentazione di Django utilizza un sistema chiamato Sphinx per convertire da testo semplice a HTML. Dovrai installare Sphinx scaricando e installando il pacchetto dal sito web di Sphinx o con
pip:$ python -m pip install Sphinx
...\> py -m pip install SphinxQuindi, usa il
Makefileincluso per trasformare la documentazione in HTML:$ cd path/to/django/docs $ make html
Avrai bisogno dell’installazione di GNU Make per questo.
Se sei in ambiente Windows puoi in alternativa usare il file batch incluso:
cd path\to\django\docs make.bat htmlLa documentazione HTML verrà piazzata in
docs/_build/html.
Differenze tra versioni¶
La documentazione nel ramo ufficiale del repository Git contiene le migliori più recenti modifiche e aggiunte. Questi cambiamenti includono la documentazione di nuove caratteristiche che mirano alla :term`prossima versione di Django. <Feature release>` Per questa ragione, vale la pena sottolineare la nostra politica per evidenziare le modifiche e le aggiunte recenti a Django.
Seguiamo questa policy:
- La documentazione di sviluppo su https://docs.djangoproject.com/en/dev/ proviene dal main branch. Questi documenti corrispondono all’ultima versione di funzionalità, oltre a tutte le funzionalità aggiunte / modificate nel framework da allora.
- Man mano che aggiungiamo funzionalità alla versione di sviluppo di Django, aggiorniamo la documentazione nella stessa transazione di commit Git.
- Per distinguere le modifiche/aggiunte di funzionalità nei documenti, usiamo la frase: «Nuovo nella versione di sviluppo di Django» per la versione di Django che non è stata ancora rilasciata, o «Nuovo nella versione X.Y» per le versioni rilasciate.
- Le correzioni e le migliorie alla documentazione possono essere riportate all’ultima branch di release a discrezione di chi le integra, in ogni caso, una volta che una varsione di Django non è più supportata, quella versione della documentazione non riceverà ulteriori aggiornamenti.
- La pagina web per la documentazione principale include link alla documentazione per le versioni precedenti. Assicurati di usare la versione della documentazione corrispondente alla versione di Django che stai usando!
