Outdated version of the documentation. Find the latest one here.

Ghidul Documentației

Introducere

Documentația QGIS se va construi în mod automat pe server la orele 0, 8am, 4pm PDT (Pacific Daylight Time). Starea curentă se poate observa la http://docs.qgis.org.

Documentația QGIS este scrisă, în principal, folosind sintaxa formatului reStructuredText (REST), cuplat cu unele script-uri din bara de instrumente Sfinx, dedicate post-procesăriinieșirii HTML. Vedeți http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html or http://sphinx.pocoo.org/markup/inline.html.

În general, atunci când se creează documentația rst pentru proiectul QGIS, vă rugăm să urmați Liniile generale ale stilului documentației Python. Mai jos sunt expuse câteva reguli generale de urmat atunci când se utilizează rst în documentația QGIS.

Dacă sunteți în căutarea unor reguli generale privind contribuția la proiectul QGIS sau privind gestionarea depozitelor de cod, ați putea găsi informații în secțiunea Implicați-vă în Comunitatea QGIS.

Scrierea Documentației

Titluri

Fiecărei pagini web a documentației îi corespunde un fișier .rst.

Secțiunile utilizate pentru structurarea textului sunt identificate prin titlul lor, care este subliniat (și pentru primul nivel). Titlurile de același nivel trebuie să folosească același caracter pentru subliniere. În Documentația QGIS, ar trebui să utilizați următoarele stiluri pentru capitol, secțiune, subsecțiune și minisecțiune.

********
Chapter
********

Section
=======

Subsection
----------

Minisec
.......

Subminisec
^^^^^^^^^^

Etichete interioare

Puteți utiliza unele etichete în interiorul textului, pentru a sublinia unele elemente.

  • Meniuri: pentru a marca o secvență completă de selecții din meniu, inclusiv pentru selectarea submeniurilor și alegerea unei anumite operații, sau orice subsecvență a unei astfel de secvențe.

    :menuselection:`menu --> submenu`
  • Titlurile Ferestrelor de Dialog și ale Filelor: Etichete prezentate ca parte a unei interfețe cu utilizatorul interactivă, inclusiv titlul ferestrei, cel al filei și etichetele opțiunilor.

    :guilabel:`title`
  • Etichetele butoanelor

    **[Apply]**
  • Numele de fișier sau directorul

    :file:`README.rst`
  • Pictogramă cu fereastră de tip balon, care aparține pictogramei

    |icon| :sup:`popup_text`

    (vedeți imaginea de mai jos).

  • Combinații de taste

    :kbd:`ctrl B`

    va arăta Ctrl B

  • Text specific utilizatorului

    ``label``
    

Etichetă/referință

Referințele sunt folosite pentru a plasa ancore în interiorul textului. Vă ajută, de asemenea, să creați și să apelați referințele dintre secțiuni sau pagini.

Exemplul de mai jos creează ancora unei secțiuni (ex.: titlul Etichetei/referinței)

.. _my_anchor:

Label/reference
---------------

Pentru a apela referința din aceeași pagină, folosiți

see my_anchor_ for more information.

ceea ce va returna:

vedeți my_anchor pentru mai multe informații.

Observați modul în care se va trece la următoarea linie/lucru care urmează ‘ancora’. În mod normal, pentru a declara această etichetă nu trebuie să utilizați apostroful, dar trebuie să utilizați linii vide înainte și după ancoră.

O altă modalitate de a sări în același loc de oriunde din documentație este de a utiliza rolul :ref:.

see :ref:`my_anchor` for more information.

care va afișa titlul în loc (în acest caz, titlul acestei secțiuni!):

vedeți Etichetă/referință pentru mai multe informații.

Deci, referința 1 (my_anchor) și referința 2 (Etichetă/referință). Deoarece referința adesea afișează un titlu complet, nu există cu adevărat nevoie să utilizăm cuvântul section. Rețineți că puteți utiliza un titlu personalizat pentru a descrie referința

see :ref:`Label and reference <my_anchor>` for more information.

returnează:

vedeți Eticheta și referința pentru mai multe informații.

Figuri și imagini

Imagini

Pentru a insera o imagine, utilizați

.. image:: /static/common/qgislogo.png
   :width: 10 em

ceea ce returnează

../../_images/qgislogo.png

Înlocuire

Puteți include o imagine în text sau să adăugați un alias pentru utilizarea globală. Pentru a utiliza o imagine într-un paragraf, doar creați un alias oriunde,

.. |nice_logo| image:: /static/common/qgislogo.png
               :width: 2 em

și apelați-l în paragraful dvs.:

my paragraph begins here with a nice logo |nice_logo|.

Iată cum va arăta acest exemplu:

paragraful meu începe cu un logo frumos nice_logo aici.

Note

În prezent, pentru a asigura coerența și pentru a ajuta în utilizarea pictogramelor QGIS este construită o listă de aliasuri, acestea fiind disponibile în capitolul Substituții.

Figuri

.. _figure_readme_1:

.. only:: html

   **Figure Readme 1:**

.. figure:: /static/common/qgislogo.png
   :width: 20 em
   :align: center

   A caption: A logo I like

Rezultatul arată în felul următor:

Figure Readme 1:

../../_images/qgislogo.png

Un text explicativ: Un logo care-mi place

Utilizați .. only:: html pentru a face vizibil numai în fișierele html numărul figurii (Figure Readme 1) . Script-urile vor introduce un număr generat automat, înainte de textul explicativ al figurii din pdf.

Pentru a utiliza un text explicativ (vedeți Textul explicativ) doar inserați text indentat după o linie vidă, în blocul figurii.

Trimiterea către figură se poate face utilizând etichete de referință ca aceasta

(see Figure_Readme_1_).

Așa va arăta ancora Figure_Readme_1. Puteți folosi majuscule, dacă doriți. Se poate utiliza în interiorul aceluiași document rst, dar nu și în alte documente .rst.

Nu mai puteți folosi :ref: pentru referințe, pentru că în html se pierde trimiterea către titlu (acum se referă la locul de dinaintea Figure Readme 1:)

see :ref:`figure_readme_1`, does not work due to the lost reference to
the caption of the figure, this is not a 'bug' but a choice we made!

Tabele

Pentru a crea o simplă tabelă

=======  =======  =======
x        y        z
=======  =======  =======
1        2        3
2        4
=======  =======  =======

Utilizați \ urmat de un spațiu vid, pentru a lăsa un spațiu gol.

Puteți folosi, de asemenea, tabele mai complicate, prin desenarea lor folosind referințe

.. _my_drawn_table_1:

+---------------+--------------------+
| Windows       | Mac OSX            |
+---------------+--------------------+
| |win|         | |osx|              |
+---------------+--------------------+
| and of course not to forget |nix|  |
+------------------------------------+

My drawn table, mind you this is unfortunately not regarded a caption

You can reference to it like this my_drawn_table_1_.

Rezultatul:

Windows Mac OSX
win osx

și, desigur, să nu uităm de nix

Tabelul trasat de mine, rețineți că acesta nu este, din păcate, un titlu

Puteți să-l referențiați astfel: my_drawn_table_1.

Index

Mai multe etichete index există în RST. Pentru a traduce indexul, este necesar să-l integrați în textul normal. În acest caz, utilizați această sintaxă:

QGIS allows to load several :index:`Vector formats` supported by GDAL/OGR ...

În cazul în care termenul nu trebuie să fie tradus, vă rugăm să utilizați această sintaxă:

.. index:: WMS, WFS, WCS, CAT, SFS, GML, ...

Note de subsol

Rețineți: Notele de subsol nu sunt recunoscute de către orice software de traducere și, de asemenea, nu sunt convertite în format pdf într-un mod corespunzător. De aceea, puteți renunța la folosirea notelor de subsol în documentație.

Aceasta va crea o notă de subsol

blabla [1]_

Care va indica:

[1]

Actualizări ale plugin-urilor de bază

Gestiunea capturilor de ecran

Adăugarea noilor capturi de ecran

Iată câteva sfaturi pentru a crea noi capturi de ecran, aspectuoase. Pentru a ghida utilizatorii, ele vor intra în ./resources/en/user_manual/

  • același mediu pentru toate capturile de ecran (același sistem de operare, aceleași decorații, aceeași dimensiune a fontului). Am folosit Ubuntu cu Unity și tema implicită “ambience”. Pentru capturi de ecran ale fereastrei principale QGIS și ale compozitorului, le-am setat pentru a afișa meniurile în fereastră (acest lucru nu este implicit în Unity).

  • reducerea ferestrei la spațiul minim necesar pentru a afișa entitatea (folosirea întregului ecran pentru o mică fereastră modală > nejustificată)

  • mai puțină dezordine, cu atât mai bine (nu este nevoie să activați toate barele de instrumente)

  • nu le redimensionați într-un editor de imagine, dimensiunea stabilindu-se în fișierele rst, dacă este necesar (reducerea dimensiunilor fără creșterea, în mod corespunzător, a rezoluției > urât)

  • tăiați fundalul

  • Setați rezoluția de imprimare la 135 dpi, folosind, de exemplu, Gimp (imagine > dimensiunea de imprimare) apoi salvați. În acest fel, în cazul în care nici o dimensiune nu este stabilită în fișierele rst, imaginile vor fi la dimensiunea originală în html, și la o rezoluție bună de imprimare în formatul PDF. Puteți utiliza comanda de conversie din ImageMagick, pentru a crea un lot de imagini:

convert -units PixelsPerInch input.png -density 135 output.png
  • să le salvați ca png (fără artefacte jpeg)

  • captura de ecran ar trebui să arate conținutul, în conformitate cu ceea ce este descris în text

  • puteți găsi unele proiecte QGIS, gata pregătite, care au fost utilizate înainte de crearea capturilor de ecran în ./qgis-projects. Acest lucru face mai ușoară reproducerea capturilor de ecran pentru următoarea versiune de QGIS. Aceste proiecte folosesc Setul de date eșantion din QGIS (cunoscut și ca Setul de date Alaska), care ar trebui să fie plasat în același folder cu Depozitul Documentației QGIS.

  • Utilizați următoarea comandă pentru a elimina funcția de meniu global în Ubuntu, pentru a crea ecrane mai mici, cu meniuri, ale aplicației.

sudo apt-get autoremove appmenu-gtk appmenu-gtk3 appmenu-qt

Traducerea Capturilor de Ecran

Iată câteva sfaturi pentru a crea capturi de ecran pentru ghidul de utilizare tradus. Ele vor intra în ./resources/<your language>/user_manual/

  • același mediu pentru toate capturile de ecran (același sistem de operare, același decor, aceeași mărime de font)

  • utilizați proiectele QGIS incluse în Depozitul Documentației QGIS (din ./qgis_projects). Acestea au fost utilizate pentru a produce capturile de ecran ‘originale’ din manual. Setul de date eșantion al QGIS (cunoscut și ca Setul de date Alaska) ar trebui să fie plasat în același folder cu Depozitul Documentației QGIS.

  • aceeași dimensiune ca și capturile ‘originale’ în limba engleză, în caz contrar acestea vor fi întinse și vor arăta urât. Dacă trebuie să aveți o dimensiune diferită datorită unor șiruri de caractere ui lungi, nu uitați să schimbați dimensiunea în codul rst al limbii dvs.

  • reducerea ferestrei la spațiul minim necesar pentru a afișa entitatea (folosirea întregului ecran pentru o mică fereastră modală > nejustificată)

  • mai puțină dezordine, cu atât mai bine (nu este nevoie să activați toate barele de instrumente)

  • nu le redimensionați într-un editor de imagine, dimensiunea stabilindu-se în fișierele rst (reducerea dimensiunilor fără creșterea, în mod corespunzător, a rezoluției > urât)

  • tăiați fundalul

  • să le salvați ca png (fără artefacte jpeg)

  • captura de ecran ar trebui să arate conținutul, în conformitate cu ceea ce este descris în text

Documentarea Algoritmilor Processing

Dacă doriți să scrieți documentație pentru algoritmii Processing țineți cont de aceste indicații:

  • nu suprascrieți fișierele de asistență existente cu fișiere din alte surse (de exemplu din arborele sursă al QGIS sau din depozitul Processing), aceste fișiere având formate diferite

  • Fișierele de asistență ale algoritmului Processing sunt parte a Ghidului Utilizatorului QGIS, așa că folosesc aceeași formatare ca și Ghidul de Utilizare, sau ca celelalte documentații

  • evitați utilizarea expresiilor de genul “Acest algoritm face cutare și cutare...” ca primă frază din descrierea algoritmului. Încercați să utilizați cuvinte mai generale, ca acelea din fișierele de asistență ale algoritmilor TauDEM sau GRASS

  • adăugați imagini dacă este necesar. Folosiți formatul PNG și urmați liniile directoare ale documentației.

  • dacă este necesar adăugați trimiteri către informații suplimentare (cum ar fi publicații sau pagini web), în secțiunea “Vedeți, de asemenea”

  • oferiți explicații clare pentru parametrii și rezultatele algoritmilor (din nou, GRASS și TauDEM sunt bune exemple)

  • nu modificați numele parametrilor sau al ieșirilor. Dacă ați găsit greșeli de ortografie — raportați-le în bugracker, astfel încât dezvoltatorii să poată depana și codul Processing

  • nu listați opțiunile disponibile în descrierea algoritmului, opțiunile fiind deja menționate în descrierea parametrului.

  • nu adăugați, fără un motiv întemeiat, informații despre tipul geometriilor vectoriale în descrierea algoritmului, deoarece aceste informații sunt deja disponibile în descrierea parametrului