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¶
These rules govern how you should write your documentation to avoid problems with style, format, or linking.
Titolo¶
All pages must have a document title that will be shown in the table of contents (left sidebar) and at the top of the page.
Titles should be «sentence cased» rather than «Title Cased». For example:
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.
Page titles are underlined with equals signs. For example, the markup for Segnalazione dei bug includes the following title:
Bug reporting
=============
Note that:
The title is sentence cased
The title is underlined with equals signs
The underline spans the title completely without going over
Incorrect examples of titles include:
Incorrect casing
Bug Reporting =============
Underline too short
Bug reporting =====
Underline too long
Bug reporting ================
Headings¶
There are several levels of headings that you may place on your page. These levels are shown here in order:
Page title
==========
Level one
---------
Level two
^^^^^^^^^
Level three
"""""""""""
Each heading level creates a sub-section in the global table of contents tree available when the documentation is built. In the primary (web) version of the documentation, this only shows four levels deep from the top level of the documentation. Please refrain from using more heading levels than will show in this tree as it makes navigating your document difficult. If you must use this many heading levels, it is a good sign that your document should be split up into multiple pages.
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.
You can do this by adding the page to the index.rst file in the same directory that you created it. For example, if you create a file called «newpage.rst», you would add the line marked with a chevron (>) in the nearest index:
.. 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.
Moving pages¶
Sometimes it becomes necessary to move a page from one place in the documentation to another. Generally this is to improve document flow: For example, it makes more sense for the page to come after a page you’ve just added in a different section.
However, people link to our documentation from many sources that we do not control. Blogs, websites, and other documentation sites can direct people here using links that they may never update. It is a terrible experience to follow a link from a different site and land on a 404 page, left to your own devices to find your way in restructured documentation.
We use a tool called Rediraffe to avoid this bad experience. Rediraffe creates redirect pages which can send a user from an old, invalid link to a new, useful link. Please create a redirect link when changing a page’s name or moving a page within the documentation’s directory structure. Redirect links are created by placing the filename of the old document and the filename of the new document, relative to the documentation’s root, in the redirects.txt file.
We use Rediraffe’s checkdiff builder to ensure that pages are not deleted from the documentation without a redirect in place. This builder is run as part of the build.sh script in the repository and as part of our automated build once you submit a Pull Request.
What follows are some examples of situations where you should create redirects.
You are moving systemdev/calendars.rst to appdev/calendars.rst. Add the following to the redirects.txt file:
"systemdev/calendars.txt" "appdev/calendars.txt"
You are moving appdev/clickable.rst into several pages in appdev/clickable/ to give significantly more information about the tool than there was previously. You have created an introduction page, appdev/clickable/introduction.rst. In this case, it would be a good idea to redirect the old page to the new introduction page. This can be done by adding the following to redirects.txt:
"appdev/clickable.rst" "appdev/clickable/introduction.rst"
Avvertimenti¶
Your edits must not introduce any warnings into the documentation build. If any warnings occur, the build will fail and your pull request will be marked with a red “X”. Please ensure that your RST is valid and correct before you create a pull request. This is done automatically (via sphinx-build crashing with your error) if you follow our build instructions below.
Line length¶
There is no restriction on line length in this repository. Please do not break lines at an arbitrary line length. Instead, turn on word wrap in your text editor.
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.
Final check of your contribution¶
After you have created your PR on github, the CI (continuous integration) system will make a test build of your contribution. Please double check whether this builds successfully and whether the result looks as you intended it to:
Scroll to the bottom of the «Conversation» tab of your PR on github, here you will see the checks (You may have to click on «Show all checks»)
It can have a yellow dot, i.e., «pending» then wait a few more seconds.
Or it may have a red X, i.e., it failed. In this case please check why it failed
If it shows a green check mark, it means the PR could be built successfully
Now please click on «Details»,
then «Artifacts» on the top right,
then «_build/html/..index.html»,
and finally on «Go to start page».
Now you can browse a complete build of the UBports docs site with your contribution included. Double check whether your changes look ok.
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¶
This section lists the TODOs that have been included in this documentation. If you know how to fix one, please send us a Pull Request to make it better!
Per creare un todo, aggiungi questo marcatore (markup) alla tua pagina:
.. todo::
My todo text
Da fare
Document the process for Nexus 4 (mako)
(L'riga originale si trova in /home/docs/checkouts/readthedocs.org/user_builds/ubports-docs-dev-it/checkouts/latest/systemdev/kernel-hal.rst, linea 57.)