Guida allo stile della documentazione¶

Questa guida contiene informazioni sullo stile previsto, sulla sintassi specifica di MkDocs, sui vari strumenti necessari e sulla traduzione della documentazione, per quanto riguarda la scrittura di nuovi contenuti e la traduzione di quelli esistenti.

Stile generale¶

Le intestazioni e i titoli devono avere solo la prima parola in maiuscolo.
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").
L'ortografia di "artefatto" e "artefatti" è quella indicata.
Usiamo uno spazio singolo dopo il punto.
Utilizziamo un singolo trattino circondato da spazi come trattino lungo (o un letterale HTML —).
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 codice in linea, avvolgendolo in singoli backtick, invece di essere aggiunto al dizionario.
Evitiamo di usare termini come "semplicemente", "solo" o "facilmente" quando descriviamo le azioni che un utente dovrebbe compiere. Questi termini possono essere interpretati come peggiorativi, specialmente quando un utente sta incontrando difficoltà.

Informazioni di riferimento incrociato¶

È consigliabile fare riferimenti incrociati ai contenuti della documentazione ogni volta che è possibile. Questa sezione illustra i vari modi per farlo, ognuno dei quali si basa sul tipo di informazioni a cui si fa riferimento.

MkDocs rende i collegamenti standard formattati in Markdown. I collegamenti ipertestuali web standard in formato Markdown sono i seguenti:

[Link text](https://example.com/)

È possibile utilizzare questo formato anche per collegarsi a un file locale:

[Link text](path/to/file.md)

Per fare riferimento a sezioni specifiche di file o alla documentazione API è necessario utilizzare il formato di collegamento di riferimento di MkDocs.

Ancoraggi Markdown personalizzati e riferimenti incrociati ai contenuti¶

Markdown genera ancore per tutte le intestazioni (qualsiasi cosa su una singola riga che inizia con un numero di simboli # compreso tra uno e sei), in base al contenuto dell'intestazione. Per esempio, l'ancora generata per questa sezione è custom-markdown-anchors-and-content-cross---referencing. Tuttavia, a causa del modo in cui funzionano le nostre traduzioni, ogni volta che si fa riferimento a un'intestazione di sezione, questa deve avere un ancoraggio personalizzato.

MkDocs supporta il rendering di una sintassi di collegamento di riferimento che consente di collegarsi a vari altri elementi della documentazione utilizzando un collegamento Markdown modificato. Questo include, tra l'altro, il collegamento a intestazioni e ancore di testo Markdown personalizzate.

I link di riferimento MkDocs sono tutti i link formattati come segue:

[Link text][link-target]

Sono necessari ancoraggi personalizzati per l'intestazione e il

contenuto

Qualsiasi intestazione o sezione di contenuto a cui si fa riferimento nel contenuto testuale tramite un link di riferimento MkDocs nella documentazione di BeeWare deve avere un ancoraggio personalizzato. Altrimenti, è possibile che i collegamenti si interrompano quando il contenuto dell'intestazione viene tradotto.

Se si ha bisogno di un collegamento a un ancoraggio di intestazione, è necessario generare un ancoraggio personalizzato per il contenuto desiderato. La sintassi generale per impostare un ancoraggio personalizzato è la seguente:

# Header text { #anchor-name }

Per esempio, la personalizzazione dell'ancora per questa sezione in custom-anchors sarebbe fatta con la seguente formattazione:

## Custom Markdown anchors { #custom-anchors }

È possibile creare un ancoraggio anche su contenuti generici, compresi testi e codeblock. La seguente formattazione, con linee nuove sopra e sotto, deve essere inclusa sopra il contenuto a cui si desidera collegare:

Content above.

[](){ #anchor-name }

Content below, that is now attached to the anchor above.

Una volta create le ancore personalizzate, è possibile collegarle all'interno dello stesso documento o in altre parti della documentazione.

Il Markdown standard è usato per collegarsi a un'ancora nello stesso file, che è formattata come segue:

[Link text](#anchor-name)

Il collegamento a un'ancora in un documento separato utilizza lo stile di riferimento di MkDocs, formattato come segue:

[Link text][anchor-name]

Link di riferimento alle API¶

Il collegamento dei riferimenti di MkDocs supporta anche i riferimenti incrociati alla documentazione dell'API, comprese le classi documentate, i metodi o gli attributi delle classi e i riferimenti a documentazione esterna specifica.

Esistono diverse opzioni per il collegamento a una classe documentata, a un metodo o a un attributo di una classe, indipendentemente dal fatto che il collegamento avvenga dallo stesso file o da un file separato. Quando ci si collega a classi, ecc. è necessario includere i trattini indietro nella prima serie di parentesi quadre per rendere il nome come codice in linea. I backtick non sono necessari solo se si utilizza un testo personalizzato che non deve essere reso come codice in linea. I trattini non devono mai essere inclusi nel secondo gruppo di parentesi quadre.

Il collegamento a una classe con la visualizzazione dello spazio dei nomi è formattato come segue:

[`module.ClassName`][]

Il collegamento a una classe, pur visualizzando solo il nome della classe, è formattato come segue:

[`ClassName`][module.ClassName]

Gli attributi sono gli stessi di cui sopra, con il nome dell'attributo incluso. Di seguito viene visualizzato lo spazio dei nomi:

[`module.ClassName.attributename`][]

Come per le classi, la visualizzazione del solo nome dell'attributo è formattata come segue:

[`attributename`][module.ClassName.attributename]

I metodi devono essere visualizzati con () dopo lo spazio dei nomi e quindi devono essere gestiti in modo diverso dagli attributi. Il modo appropriato per collegarsi a un metodo è il seguente:

[`module.ClassName.methodname()`][module.ClassName.methodname]

Di seguito viene visualizzato solo il nome della classe e del metodo. È inoltre necessario includere le parentesi dopo il nome:

[`Classname.methodname()`][module.Classname.methodname]

È possibile collegarsi a una classe, a un metodo o a un attributo visualizzando un testo arbitrario, utilizzando lo stesso metodo con lo spazio dei nomi applicabile. Per fare questo con una classe, la formattazione è la seguente:

[link text][module.ClassName]

È anche possibile collegarsi direttamente alla documentazione del nucleo di Python, così come alla documentazione di Pillow. Ad esempio, per collegarsi alla documentazione di int:

[`int`][]

Per collegarsi alla documentazione di `Image' di Pillow:

[`PIL.Image.Image`][]

Suggerimenti per i blocchi di codice¶

Evidenziazione della lingua e del codice¶

È possibile specificare la lingua per il codice contenuto nel blocco di codice includendo il nome della lingua dopo i primi tre trattini, senza spazi intermedi. In questo modo, il codice viene evidenziato in modo appropriato durante il rendering. Per esempio, per specificare Python, si dovrebbe iniziare il codeblock con `python.

Comandi della console e pulsante di copia¶

Se si includono comandi da console o comandi con output, etichettarli come console o doscon, a seconda che si stia descrivendo un sistema operativo Unix-like (incluso macOS) o Windows. È possibile includere il prompt fornito dal sistema operativo; solo il comando verrà copiato quando si fa clic sul pulsante di copia. Per esempio, se si inizia un codeblock con ``console'' e si include il seguente contenuto:

$ mkdir test
$ ls
test

Quindi, facendo clic sul pulsante di copia del blocco di codice, si copieranno solo i comandi, ignorando le richieste e l'output. Questo permette di indicare che si tratta di comandi della console, pur consentendo agli utenti di utilizzare efficacemente il pulsante di copia.

Evidenziazione di linee di codice specifiche¶

È possibile evidenziare righe specifiche di codice. Per esempio, per evidenziare la riga 2, si aggiunge uno spazio dopo il linguaggio, seguito da {hl_lines="2"}. Quindi, il blocco di codice inizierebbe con ``python {hl_lines="2"}. Il risultato è:

import toga
from toga.style.pack import COLUMN, ROW

È possibile evidenziare più righe diverse. Per esempio, python {hl_lines="3 5 9"} evidenzierebbe le righe 3, 5 e 9. È anche possibile evidenziare un intervallo di righe. Per esempio, python {hl_lines="3-8"} evidenzia le righe da 3 a 8. È possibile evidenziare più intervalli con, ad esempio, python {hl_lines="9-18 23-44"}.

Elementi di Markdown che richiedono una formattazione specifica¶

A causa del modo in cui vengono generati i file di traduzione, è importante includere le newline necessarie nella sintassi di Markdown per le ammonizioni, le note, le schede, le direttive Jinja, le didascalie e l'allineamento delle immagini, ecc.

Ammonizioni e note¶

Le ammonizioni devono essere formattate come segue, assicurando anche una linea nuova prima e dopo l'inizio e la fine dell'ammonizione:

Content above.

/// admonition | Title

Admonition text.

A second paragraph.

///

Content below.

Questo funziona allo stesso modo con qualsiasi tipo di avvertimento supportato. Ad esempio, gli avvertimenti relativi alle note richiedono la stessa formattazione e gli stessi caratteri di nuova riga:

Content above.

/// note | Note title

Note text here.

///

Content below.

Tutti i tipi di ammonimento supportati sono disponibili per l'uso come ammonimenti.

Contenuto a schede¶

Il contenuto della scheda è formattato come segue, con una newline inclusa prima dell'inizio e dopo la fine del blocco di contenuto:

Content above.

/// tab | Tab one title

Tab one text

///

/// tab | Tab two title

Tab two text.

///

/// tab | Tab three title

Tab three text.

///

Content below.

Una scheda con un'ammonizione annidata verrebbe formattata come segue, includendo una newline prima e dopo il blocco di contenuto:

Content above.

/// tab | Windows

Tab text.

/// admonition | Admonition

Admonition text.

///

///

Content below.

Contenuto collassato¶

Il contenuto compresso è formattato come segue, inclusi i caratteri di nuova riga:

Content above.

/// details-note | Collapsed content title

Collapsed content.

///

Content below.

Tutti i tipi di avvertenza supportati sono disponibili per l'uso con i contenuti compressi, tuttavia è necessario dichiararli come details-admonitiontype. Quindi, un blocco compresso di tipo "nota" sarebbe details-note (come mostrato sopra), un blocco compresso di tipo "avviso" sarebbe details-warning e così via.

Direttive Jinja¶

Ci sono alcune caratteristiche della documentazione che utilizzano le direttive Jinja nel testo. Tutto ciò che utilizza le funzioni delle direttive Jinja deve essere avvolto da newline. Per esempio, il tutorial di BeeWare contiene condizionali Jinja basati su variabili per determinare quale ammonizione mostrare nella pagina principale. Questi sono formattati come segue:

Content above.



Content below.

Esiste anche una sintassi per la sostituzione di simboli o testo. Questa sintassi consiste in una variabile avvolta in una coppia di doppie parentesi graffe corrispondenti e, se si trova su una riga propria, deve includere una newline prima e dopo.

Content above.

{{ variable }}

Content below.

Formattazione dell'immagine¶

Le immagini possono essere impostate in larghezza e possono essere allineate a sinistra, a destra e al centro (con un'avvertenza sul "centro"). Le immagini dovrebbero sempre includere un testo alt significativo ai fini dell'accessibilità.

L'impostazione della larghezza di 300px su un'immagine verrebbe formattata come segue:

![Image alt text](../path/to/image.png){ width="300px" }

L'allineamento di un'immagine a sinistra (o a destra) verrebbe formattato come segue:

![Image alt text](../path/to/image.png){ align=left }

L'aggiunta di una didascalia a un'immagine richiede una linea nuova prima e dopo e viene formattata come segue:

Content above.

![Image alt text](/path/to/image.png)

/// caption

Caption content.

///

Content below.

L'allineamento al centro di un'immagine non è possibile con l'attributo align. La soluzione consiste nel far seguire all'immagine una didascalia vuota, che verrà centrata. È necessario includere dei newline tra ogni sezione e prima e dopo. È formattato come segue:

Content above.

![Image alt text](../path/to/image.png)

/// caption

///

Content below.

Plugin con formattazione Markdown specifica¶

Le sezioni seguenti spiegano come utilizzare i plugin che richiedono una specifica formattazione Markdown.

Utilizzo degli Snippet per includere contenuti esterni¶

Per i dettagli su come includere contenuti esterni da un file locale o da un URL, vedere la documentazione dell'estensione Snippets. Snippets dovrebbe essere usato a patto che il documento non contenga direttive Jinja che devono essere eseguite (l'esecuzione di Jinja avviene parallelamente all'elaborazione di Snippets e quindi qualsiasi Jinja nel file non verrà elaborato). Snippets è necessario se si vogliono usare delimitatori che permettano di includere parti specifiche di un file separatamente, ad esempio se il documento sorgente è diviso in sezioni da iniettare separatamente l'una dall'altra.

Note importanti:

Si usa -8<- come identificatore di Snippets. La documentazione mostra diverse opzioni; si consiglia di seguire il nostro stile.
I file presenti nei contenuti condivisi di BeeWare Docs Tools sono trattati come contenuti "locali". Pertanto, si userà solo il nome del file, come in -8<- "docs-style-guide.md", oppure, se il contenuto è in una sottodirectory, solo la directory e il nome del file, come in -8<- "style/docs-style-guide.md".
Se si include un contenuto esterno da un file su GitHub tramite un URL, è necessario utilizzare l'URL del contenuto grezzo, altrimenti verrà visualizzata l'intera pagina web incorporata ovunque la si includa.

Utilizzo delle macro per includere il contenuto di BeeWare Docs Tools condiviso¶

È anche possibile includere il contenuto della cartella dei contenuti condivisi degli strumenti BeeWare Docs utilizzando il plugin Macros MkDocs. Questo metodo è necessario se il documento contiene direttive Jinja che devono essere eseguite e deve essere usato solo in questa situazione. Non funziona con il contenuto esterno tramite un URL. Il meccanismo di sostituzione delle variabili di Macros funziona con questo metodo.

Esistono opzioni per includere i contenuti utilizzando le macro:

Usare la sintassi include di Jinja se si vuole includere il documento senza altre modifiche manuali.
Utilizzare la sintassi extends di Jinja se si è inclusa la sintassi block di Jinja nel documento, che consente di sovrascrivere o aggiungere a sezioni specifiche.

`pyspelling`¶

Utilizziamo il correttore ortografico pyspelling. Viene eseguito durante i controlli di lint.

Quando pyspelling identifica una parola scritta male, nella maggior parte dei casi, dovrebbe essere corretta nel contenuto della documentazione.

Nel raro caso in cui identifichi una parola valida che non è presente nel dizionario pyspelling, si hanno due opzioni:

Se si tratta di una parola che probabilmente verrà riutilizzata più volte, si dovrebbe aggiungere la parola al documento spelling_wordlist nella directory docs, in ordine alfabetico.
Se si tratta di una parola che difficilmente verrà usata di nuovo, è possibile inserirla in un tag <nospell> / </nospell> e pyspelling la ignorerà in linea.