Documentazione#

Suggerimento

La documentazione su questo sito è scritta in ReStructuredText o RST in breve. Si prega di controllare il RST Primer <http://www.sphinx-doc.org/en/stable/rest.html> _ se non si ha familiarità con RST.

Questa pagina ti guiderà attraverso la corposa documentazione del progetto UBports che può essere descritto su questo sito.

Linee guida per la documentazione#

Queste regole governano come dovresti scrivere la tua documentare per evitare problemi di stile, formato e di collegamenti.

Titolo#

Tutte le pagine devono aver un titolo di documento, che sarà mostrato nell’indice (a sinistra) in cima alla pagina.

I titoli devono essere «a frase» piuttosto che «a titolo». Ad esempio:

Incorrect casing:
    Writing A Good Bug Report
Correct casing:
    Writing a good bug report
Correct casing when proper nouns are involved:
    Installing Ubuntu Touch on your phone

Non c’è una sola definizione di formattazione titolo che tutti seguano, ma la formattazione della affermazioni è facile. Questo rende la formattazione dell’indice consistente.

I titoli delle pagine sono sottolineati con i segni di uguale. Per esempio, il markup di Segnalazione dei bug include il seguente titolo:

Bug reporting
=============

Si noti che:

Il titolo è incassato a frase
Il titolo è sottolineato con i segni di uguale
La sottolineatura attraversa completamente il titolo senza oltrepassarlo

Esempi di titoli non corretti sono:

Involucro errato
Bug Reporting =============
Sottolineare troppo breve
Bug reporting =====
Sottolineare troppo
Bug reporting ================

Denominazioni#

Ci sono diversi livelli di intestazioni che potete inserire nella vostra pagina. Questi livelli sono mostrati qui in ordine:

Page title
==========

Level one
---------

Level two
^^^^^^^^^

Level three
"""""""""""

Ogni livello di intestazione crea una sottosezione nella tabella globale dell’albero dei contenuti disponibile quando la documentazione è costruita. Nella versione(web) primaria della documentazione, questo mostra solo quattro livelli profondi dal livello superiore della documentazione. Si prega di astenersi dall’utilizzo di più livelli di intestazione di mostrare in questo albero in quanto rende difficile la navigazione del documento. Se è necessario utilizzare molti livelli di intestazione, è un buon segno che il documento deve essere diviso in più pagine.

Indice#

Gli utenti non possono navigare nella tua pagina nuova se non riescono a trovarla. Tanto meno Sphinx. Ecco perchè hai bisogno di aggiungere pagine nuove all’indice di Sphinx.

Lo puoi fare aggiungendo la pagina nel file index.rst nella stessa directory che hai creato. Ad esempio, se crei un file chiamato «newpage.rst», aggiungerai una linea marcata con un simbolo di maggiore (chevron o >) nell’indice più prossimo:

.. toctree::
    :maxdepth: 1
    :name: example-toc

    oldpage
    anotheroldpage
>   newpage

L’ordine è importante. Se vuoi che la tua pagina appaia in un certo punto dell’indice, mettilo lì. Nell’esempio precedente, newpage sarebbe stata aggiunta alla fine dell’indice.

Pagine mobili#

A volte diventa necessario spostare una pagina da un posto nella documentazione ad un altro. Generalmente questo è per migliorare il flusso dei documenti: Ad esempio, ha più senso per la pagina venire dopo una pagina che hai appena aggiunto in una sezione diversa.

Tuttavia, le persone collegano alla nostra documentazione da molte fonti che non controlliamo. Blog, siti web e altri siti di documentazione possono indirizzare le persone qui utilizzando link che potrebbero non aggiornare mai. È un’esperienza terribile seguire un link da un sito e un terreno diverso su una pagina 404, lasciato ai propri dispositivi per trovare la vostra strada nella documentazione ristrutturata.

Usiamo uno strumento chiamato Rediraffe per evitare questa brutta esperienza. Rediraffe crea pagine redirect che possono inviare un utente da un vecchio link non valido a un nuovo link utile. Si prega di creare un link redirect quando si modifica il nome di una pagina o si sposta una pagina all’interno della struttura della directory della documentazione. I link redirect vengono creati mettendo il nome del file del vecchio documento e il nome del file del nuovo documento, relativo alla radice della documentazione, nei redirects.txt file.

Utilizziamo il costruttore checkdiff di Rediraffe per garantire che le pagine non vengano eliminate dalla documentazione senza un reindirizzamento di posizione. Questo costruttore è eseguito come parte dello script ``build.sh``nel repository e come parte della nostra build automatizzata una volta che si invia una Richiesta di Pull.

Ciò che segue sono alcuni esempi di situazioni in cui si dovrebbe creare redirect.

Si sta muovendo systemdev/calendars.rst` a ``appdev/calendars.rst. Aggiungi quanto segue al file redirects.txt:

"systemdev/calendars.txt" "appdev/calendars.txt"

Stai muovendo appdev/clickable.rst in diverse pagine in appdev/clickable/ per dare significativamente più informazioni sullo strumento di quanto non ci fosse in precedenza. Hai creato una pagina di introduzione, appdev/clickable/introduction.rst. In questo caso, sarebbe una buona idea reindirizzare la vecchia pagina alla nuova pagina di introduzione. Questo può essere fatto aggiungendo il seguente a redirects.txt:

"appdev/clickable.rst" "appdev/clickable/introduction.rst"

Avvertimenti#

Le tue modifiche non devono introdurre alcun avviso nella creazione della documentazione. Se si verificano avvertimenti, la build fallirà e la tua richiesta pull sarà contrassegnata con una “X” rossa. Assicurati che il tuo RST sia valido e corretto prima di creare una richiesta pull. Questo viene fatto automaticamente (tramite sphinx-build crash con il vostro errore) se si segue :ref: `le nostre istruzioni di costruzione <doc-contribution-workflow>`di seguito.

Lunghezza della linea#

In questo repository non ci sono restrizioni sulla lunghezza delle righe. Si prega di non interrompere le righe a una lunghezza arbitraria. Attivare invece il word wrap nel proprio editor di testo.

Flusso del contributo#

I seguenti passaggi ti aiuteranno a contribuire a questa documentazione dopo aver scritto un documento.

Nota

Avrai bisogno di un accesso a GitHub per completare questi passi. Se non ne avessi uno, fai click qui per iniziarne il processo di creazione.

Duplicando i repository#

Puoi fare delle modifiche più avanzate alla nostra documentazione deviando da ubports/docs.ubports.com in GitHub. Se non fossi sicuro come farlo, controlla l’eccellente guida di GitHub sui progetti di deviazione (forking projects).

Creazione della documentazione#

Se volessi creare questa documentazione prima di inviare una PR (come dovrebbe essere), segui queste istruzioni per la tua copia locale della tua deviazione del repository.

La documentazione può essere creata eseguendo ./build.sh nella radice di questo repository. Lo script creerà anche un ambiente virtuale di creazione ~/ubportsdocsenv, qualora non fosse presente.

Se tutto andasse bene, potrai accedere alla cartella _build e aprire index.html per vedere la documentazione di UBports.

Se riscontri problemi nel compilare la documentazione, la prima cosa da tentare è rimuovere l’ambiente di sviluppo. Esegui il comando rm -r ~/ubportsdocsenv e tenta di nuovo la compilazione. A seconda di quando hai utilizzato per la prima volta lo script di compilazione, potresti aver bisogno di avviare il comando rm con sudo.

Verifica finale del contributo#

Dopo aver creato il PR su github, il sistema CI (continuous integration) eseguirà una build di prova del vostro contributo. Si prega di controllare se la compilazione è andata a buon fine e se il risultato è quello desiderato:

Scorrere in fondo alla scheda «Conversazione» della propria PR su github, per vedere i controlli (potrebbe essere necessario cliccare su «Mostra tutti i controlli»)
Può avere un punto giallo, cioè «in attesa», quindi attendere qualche altro secondo.
Oppure può avere una X rossa, cioè fallita. In questo caso, verificare il motivo del fallimento
Se viene visualizzato un segno di spunta verde, significa che la PR può essere costruita con successo
Ora cliccate su «Dettagli»,
poi «Artefatti» in alto a destra,
poi «_build/html/..index.html»,
e infine su «Vai alla pagina iniziale».

Ora è possibile consultare una build completa del sito dei documenti di UBports con il proprio contributo incluso. Verificate se le vostre modifiche sono corrette.

Metodi alternativi per contribuire#

Traduzioni#

Puoi trovare i componenti di questo documento da tradurre in its project in UBports Weblate.

Scrivere documenti non nel formato RST#

In caso ti interessasse scrivere documenti per UBports ma non sei a tuo agio nel compilare un TestoRistrutturato, ti preghiamo di scriverlo e postarlo su UBports Forum nella relativa sezione (verosimilmente General). Qualcuno ti aiuterà a revisionare la tua bozza e a scrivere il TestoRistrutturato richiesto.

Scomodo con Git#

Se hai scritto un documento completo in ReStructuredText ma non ti trovi bene a usare Git o GitHub, pubblicalo in UBports Forum nella sezione adeguata (probabilmente in General). Qualcuno ti aiuterà a correggere la bozza e a inviarlo a questa documentazione.

Attuali TODOs#

Questa pagina elenca i DAFAREs che sono state incluse in questo documento. Se sai come risolverne uno, mandaci una PR per farlo come si deve!

Per creare un todo, aggiungi questo marcatore (markup) alla tua pagina:

.. todo::

   My todo text

Da fare

There is also another way to create somewhat more featureful webapps, sometimes referred to as webapp+ or alternative container. This needst to be properly documented. It’s a simple qml app that can be easily configured. Creation is almost as simple as “classic” webapp, but result is more powerfull with the a nice navigation feature. A rather advanced example of this is the YouTube app from Mateo Salta which has quite some modifications on top of the template.

(L'riga originale si trova in /home/docs/checkouts/readthedocs.org/user_builds/docsubportscom-italian/checkouts/latest/appdev/webapp/index.rst, linea 19.)

Da fare

Documentare il processo per Nexus 4 (mako)

(L'riga originale si trova in /home/docs/checkouts/readthedocs.org/user_builds/docsubportscom-italian/checkouts/latest/systemdev/kernel-hal.rst, linea 57.)