Documentació¶

Truc

La documentació d’aquest lloc està escrita en ReStructuredTex, o, abreujadament, RST. Si us plau mireu RST Primer si no coneixeu el RST.

Aquesta pàgina us guiarà en la escriptura de magnifica documentació per al projecte UBports que es pot mostrar a aquest lloc.

Directrius de la documentació¶

Aquest normes regulen com hauríeu d’escriure la documentació per evitar problemes amb l’estil, el format o els enllaços. Si no seguiu aquestes directriu, no acceptarem el vostre document.

Títol¶

Totes les pàgines han de tenir un títol de document que mostrarà a la taula de continguts (barra lateral esquerra) i a la part superior de la pàgina. Aquest títol està subratllat per signes d’igual.

Els títols haurien de basar-se en frases i no sols títols. Per exemple:

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

No hi ha una definició única sobre com fer títols amb frases que tothom segueix, però fer títol amb frases és senzill. Això ajuda a mantenir les majúscules consistents a la taula de continguts.

Els títols de les pàgines estan subratllats amb signes iguals. Per exemple, el marcatge per a Informació d’errors, inclou el títol següent:

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

Tingueu en compte que:

El títol és una frase casada
El títol està subratllat amb signes iguals
El subratllat abasta el títol per complet sense passar

Exemples incorrectes de títols inclouen:

L’envolvent és incorrecte
Bug Reporting =============
Subratllat massa curt
Bug reporting =====
Subratlla massa
Bug reporting ================

Advertiments¶

Hi ha diversos nivells d’encapçalaments que podeu posar en una pàgina. Aquests nivells es mostren aquí en ordre:

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

Level one
---------

Level two
^^^^^^^^^

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

Si us plau, abstenir-se d’utilitzar més de quatre nivells. Si creieu que necessiteu més nivells, és un bon senyal que el document s’ha de dividir en múltiples pàgines. A més, la versió web de la documentació només mostra quatre nivells en la seva taula de continguts.

Taula de continguts¶

Si afegiu una pàgina nova també heu d’afegir-la a la taula de continguts. Això ho podeu fer afegint la pàgina al fitxer index.rst al mateix directori on el vau crear. Per exemple, si creeu un fitxer anomenat «paginanova.rst», afegiríeu la línia marcada amb un signe de més gran (>) a l’índex més proper:

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

    oldpage
    anotheroldpage
>   newpage

L’ordre importa. Si us agradaria que la vostra pàgina aparegui a un lloc determinat de la taula de continguts, ubiqueu-la allà. A l’exemple anterior, paginanova s’afegiria al final de la taula de continguts.

S’estan movent les pàgines¶

De vegades es fa necessari traslladar una pàgina d’un lloc de la documentació a un altre. Generalment això és per millorar el flux de documents: Per exemple, té més sentit que la pàgina vingui després d’una pàgina que acabeu d’afegir en una secció diferent.

No obstant això, la gent enllaça amb la nostra documentació de moltes fonts que no controlem. Els blogs, els llocs web i altres llocs de documentació poden dirigir les persones aquí utilitzant enllaços que potser mai actualitzaran. És una experiència terrible seguir un enllaç des d’un lloc diferent i aterrar en una pàgina 404, veient-se obligat a buscar manualment en la nostra documentació.

Utilitzem una eina anomenada Rediraffe per evitar aquesta mala experiència. Rediraffe crea pàgines de redirecció, que poden enviar un usuari des d’un enllaç antic i invàlid a un enllaç nou i útil. Creeu un enllaç de redirecció quan canvieu el nom d’una pàgina o moveu una pàgina dins de l’estructura de directoris de la documentació. Els enllaços redirigits es creen col·locant el nom de fitxer del document antic i el nom de fitxer del document nou, en relació amb l’arrel de la documentació, al fitxer theredirects.txt.

Utilitzem el constructor checkdiff de Rediraffe per assegurar que les pàgines no s’esborren de la documentació sense una redirecció al seu lloc. Aquest constructor s’executa com a part de l’script build.sh al repositori i com a part de la nostra compilació automatitzada una vegada que envieu una sol·licitud de fusió (MR).

El que segueix són alguns exemples de situacions en què s’han de crear redireccionaments.

Esteu movent systemdev/calendars.rst a appdev/calendars.rst. Afegeix el següent al fitxer redirects.txt:

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

Esteu movent appdev/clickable.rst a diverses pàgines de appdev/clickable/ per a donar molta més informació sobre l’eina de la que hi havia anteriorment. Heu creat una pàgina d’introducció, appdev/clickable/introduction.rst. En aquest cas, seria una bona idea redirigir la pàgina antiga a la nova pàgina d’introducció. Això es pot fer afegint el següent a redirects.txt' :

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

Advertiments¶

Les vostres edicions no han d’introduir cap advertiment a la compilació de la documentació. Si es produeix cap advertiment, la compilació fallarà i la vostra demanda de baixada es marcarà amb una «X» vermella. Si us plau assegureu-vos que el vostre RST és vàlid i correcte abans de crear una demanda de fusió. Això es fa automàticament (mitjançant la fallada de sphinx-build amb el vostre error) si seguiu les nostres instruccions de compilació de sota.

Longitud de la línia¶

No hi ha cap restricció sobre la longitud de la línia en aquest repositori. Si us plau, no trenquis línies a una longitud de línia arbitrària. En lloc d’això, activeu l’ajust de paraules en el vostre editor de text.

Flux de treball de les contribucions¶

Després que hàgiu escrit un document, els passos següents us ajudaran a fer una contribució a aquesta documentació.

Nota

Us caldrà un compte del GitHub per completar aquests passos. Si no en teniu una, cliqueu aquí per començar el procés de crear un compte.

Bifurcació del repositori¶

Podeu fer edicions més avançades de la nostra documentació bifurcant ubports/docs.ubports.com al Gitlab.

Compilació de la documentació¶

Per compilar aquesta documentació seguiu aquestes instruccions a la còpia local de la vostra bifurcació del repositori.

Es pot compilar la documentació executant ./build.sh a l’arrel d’aquest repositori. L’script crearà també un entorn virtual de compilació a ~/ubportsdocsenv, si no n’hi ha cap present.

Si tot ha anat bé, podeu entrar el directori _build/html i obrir index.html per veure la documentació de l’UBports.

Si teniu algun problema en la compilació dels documents, el primer a provar és eliminar l’entorn de compilació. Executeu rm -r ~/ubportsdocsenv i proveu un altre cop la compilació.

Comprovació final de la teva aportació¶

Després d’haver creat la vostra sol·licitud de fusió a GitLab, el sistema d’integració contínua (CI) farà una prova de construcció de la vostra contribució (un «pipeline»). Si us plau, comproveu doblement si això es construeix correctament i si el resultat es veu com ho vau voler:

a la part superior de la pestanya «Overview» del seu MR a gitlab veurà l’estat del gasoducte
Si diu «Comprovant l’estat de la canonada» o «Pipeline running», espereu un altre minut.
si diu «Pipeline failed» amb una X vermella i, a continuació, alguna cosa va sortir malament, si us plau, feu clic a l’enllaç per trobar els detalls
Si diu «Pipeline pass» amb marca de xec verd, significa que el MR podria ser construït amb èxit i es pot procedir a mirar els resultats
ara feu clic a l’enllaç d’aquesta canonada
feu clic a la tasca «build»
Això us porta al final del registre de construcció, on veureu un missatge: «Construeix amb èxit, navegueu per l’artefacte aquí»
Fes clic a l’enllaç que hi ha al costat per veure la versió completa del lloc de documentació d’UBports amb els teus canvis
comprova doblement si els canvis es veuen bé

Mètodes alternatius per contribuir¶

Traduccions¶

Podeu trobar els components d’aquest document per traduir a its project in UBports Weblate.

Escriptura de documents en formats diferents al RST¶

Si volguéssiu escriure documents per a l’UBports però no us agrada escriure RestructuredText, si us plau escriviu-lo sense format i publiqueu-lo al UBports Forum a la secció rellevant (probablement General). Algú us podrà ajudar a revisar el vostre esborrany i a escriure el ReStructuredText requerit.

Incomoditat amb Git¶

Si heu escrit un document complet amb el ReStructredText però no teniu comoditat usant Git o GitHub, si us plau publiqueu-lo al UBports Forum a la secció rellevant (probablement General). Algú us podrà ajudar a revisar el vostre esborrany i a pujar-lo a aquesta documentació.

PER FER actuals¶

Aquesta pàgina presenta una llista dels PER FER que s’han inclòs a aquesta documentació. Si sabeu com arreglar un PER FER, si us plau envieu-nos una demanda d’incorporació de canvis per fer-lo millor!

Per crear un per fer, afegiu aquest marcatge a la vostra pàgina:

.. todo::

   My todo text

Tasca pendent

Considereu també escriure un document sobre el procés de tractar amb les sol·licituds de fusió.

(L'entrada original es troba a /home/docs/checkouts/readthedocs.org/user_builds/docsubportscom-gitlab-ca/checkouts/latest/about/process/issue-tracking.rst, línia 36).

Tasca pendent

També hi ha una altra manera de crear webapps una mica més característiques, de vegades anomenades webapp+ o contenidor alternatiu. Cal documentar-ho adequadament. És una aplicació senzilla de qml que es pot configurar fàcilment. La creació és gairebé tan simple com la webapp «clàssica», però el resultat és més potent amb una bona funció de navegació. Un exemple bastant avançat d’això és l’aplicació YouTube de Mateo Salta que té bastants modificacions a la part superior de la plantilla.

(L'entrada original es troba a /home/docs/checkouts/readthedocs.org/user_builds/docsubportscom-gitlab-ca/checkouts/latest/appdev/webapp/index.rst, línia 19).

Tasca pendent

Documenta el procés per al Nexus 4 (mako)

(L'entrada original es troba a /home/docs/checkouts/readthedocs.org/user_builds/docsubportscom-gitlab-ca/checkouts/latest/systemdev/kernel-hal.rst, línia 57).

Amfitrió ReadTheDocs¶

El lloc web Thedocuments <https://docs.ubports.com> The real està construït i allotjat per a nosaltres pel projecte theRead The Docs <https://readthedocs.org>.. La nostra configuració RTD conté un projecte principal per a l’anglès i un projecte addicional per a cada llengua suportada afegit com a traduccions al projecte principal. Si sou un mantenidor i voleu afegir un idioma, primer creeu un projecte nou amb importació manual i establiu l’idioma de manera adequada. A continuació, afegiu-ho com a traducció a la pàgina d’administració del projecte principal.