Важно

Prevod je zajednički napor :ref:`možete se pridružiti `. Ova stranica je trenutno prevedena na |napredak prevođenja|.

2. Smernice za pisanje

Uopšteno, pri pravljenju reST dokumentacije za QGIS projekat, pratite smernice za stil Python dokumentacije. Radi praktičnosti, ispod pružamo skup opštih pravila na koja se oslanjamo pri pisanju QGIS dokumentacije.

2.1. Pisanje dokumentacije

2.1.1. Naslovi

Svakoj veb stranici dokumentacije odgovara .rst datoteka.

Odeljci koji se koriste za strukturiranje teksta prepoznaju se po svom naslovu koji je podvučen (a za prvi nivo i nadvučen). Naslovi istog nivoa moraju koristiti isti znak za ukras podvlačenja. Naslovima odeljaka prethodi prazan red. U QGIS dokumentaciji treba da koristite sledeće stilove za poglavlje, odeljak, pododeljak i minisec.

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

Section
=======

Subsection
----------

Minisec
.......

Subminisec
^^^^^^^^^^

2.1.2. Liste

Liste su korisne za strukturiranje teksta. Evo nekih jednostavnih pravila zajedničkih svim listama:

  • Sve stavke liste počinjite velikim slovom

  • Ne koristite interpunkciju posle stavki liste koje sadrže samo jednu jednostavnu rečenicu

  • Koristite tačku ( . ) kao interpunkciju za stavke liste koje se sastoje od više rečenica ili jedne složene rečenice

2.1.3. Uvlačenje

Uvlačenje u reStructuredText-u treba poravnati sa oznakom liste ili markupa. Takođe je moguće praviti blok citate uvlačenjem. Pogledajte Specifikaciju

#. In a numbered list, there should be
   three spaces when you break lines
#. And next items directly follow

   * Nested lists
   * Are also possible
   * And when they also have
     a line that is too long,
     the text should be naturally
     aligned
   * and be in their own paragraph

However, if there is an unindented paragraph, this will reset the numbering:

#. This item starts at 1 again

2.1.4. Ugrađene oznake

Oznake možete koristiti za isticanje stavki.

  • GUI menija: za označavanje potpune sekvence izbora u meniju, uključujući izbor podmenija i konkretne operacije, ili bilo koje podsekvence takve sekvence.

    :menuselection:`menu --> submenu`

  • Naslovi dijaloga i kartica: Natpisi predstavljeni kao deo interaktivnog korisničkog interfejsa, uključujući naslove prozora, naslove kartica, natpise dugmadi i opcija.

    :guilabel:`title`

  • Nazivi datoteka i direktorijuma

    :file:`README.rst`

  • Ikone sa iskačućim tekstom

    |iconView| :sup:`popup_text`

    (pogledajte image ispod).

  • Prečice na tastaturi

    :kbd:`Ctrl+B`

    prikazaće Ctrl+B

    Pri opisivanju prečica na tastaturi treba koristiti sledeće konvencije:

    • Slovni tasteri se prikazuju velikim slovima: S

    • Specijalni tasteri se prikazuju sa velikim prvim slovom: Esc

    • Kombinacije tastera se prikazuju sa znakom + između tastera, bez razmaka: Shift+R

  • Korisnički tekst

    ``label``

  • Nazivi slojeva, baza podataka, tabela ili kolona

    Pri upućivanju na slojeve, baze podataka, tabele ili kolone, formatirajte kao ugrađeni kôd:

    ``layer name``
``database_name``
``table_name``
``column_name``

2.1.5. Natpisi/reference

Sidra unutar teksta mogu se koristiti za pravljenje hiperlinkova ka odeljcima ili stranicama.

Primer ispod pravi sidro odeljka (npr. Naslov natpisa/reference)

.. _my_anchor:

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

Da biste pozvali referencu na istoj stranici, koristite

see my_anchor_ for more information.

što će vratiti:

pogledajte my_anchor za više informacija.

Imajte u vidu da će skočiti na liniju/stvar koja sledi posle „sidra“. Ne morate koristiti apostrofe, ali morate imati prazne redove posle sidra.

Još jedan način za skok na isto mesto sa bilo kog mesta u dokumentaciji jeste korišćenje uloge :ref:.

see :ref:`my_anchor` for more information.

što će umesto toga napraviti link sa natpisom (u ovom slučaju naslovom ovog odeljka!):

pogledajte Natpisi/reference za više informacija.

Dakle, referenca 1 (my_anchor) i referenca 2 (Natpisi/reference). Pošto referenca često prikazuje pun natpis, nije zaista neophodno koristiti reč odeljak. Imajte u vidu da možete koristiti i prilagođen natpis za opis reference:

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

što vraća:

pogledajte Natpis i referenca za više informacija.

2.1.6. Slike i ilustracije

Slike

Da biste umetnuli sliku, koristite

.. figure:: /static/common/logo.png
   :width: 10 em

što vraća

../../_images/logo.png

Zamena ikonom

Sliku možete dodati unutar tekstualnog pasusa (npr. kao ikonu alatke). Da biste to uradili, prvo morate napraviti alijas (nazvan i zamena), što je referentni naziv koji se koristi za prikaz ikone. Radi obezbeđivanja doslednosti u dokumentima i pomoći pri korišćenju ikona, održavamo listu u datoteci substitutions.txt u korenu ovog repozitorijuma. Više detalja pronađite u poglavlju Zamene.

Korišćenje zamene ikonom obično se postiže kroz ove korake:

  1. Dodajte zamenu ikonom u datoteku substitutions.txt kao ispod. Ako zamena za ikonu koju želite da koristite već postoji, preskočite ovaj korak.

    .. |logo| image:: /static/common/logo.png
   :width: 1 em

  2. Pozovite je u svom pasusu:

    My paragraph begins here with |logo|.

  3. Dodajte (ponovo) zamenu ikonom na kraju datoteke koju menjate. Ovo pomaže u povezivanju teksta zamene sa stvarnom slikom, a može se uraditi kopiranjem iz substitutions.txt ili izvršavanjem skripte scripts/find_set_subst.py.

    Ovako će primer biti prikazan:

    Moj pasus počinje ovde sa logo.

Slika

.. _figure_logo:

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

   A caption: A logo I like

Rezultat izgleda ovako:

../../_images/logo.png

Сл. 2.24 Natpis: Logo koji volim

Da biste izbegli sukobe sa drugim referencama, sidra slika uvek počinjite sa _figure_ i koristite termine koji se lako povezuju sa natpisom slike. Iako je za sliku obavezno samo centrirano poravnanje, slobodno koristite bilo koje druge opcije za slike (kao što su width, height, scale…) ako je potrebno.

Skripte će umetnuti automatski generisan broj pre natpisa slike u generisanim HTML i PDF verzijama dokumentacije.

Da biste koristili natpis (pogledajte Moj natpis), samo umetnite uvučen tekst posle praznog reda u bloku slike.

Na sliku se može uputiti pomoću oznake reference ovako:

see :numref:`figure_logo`

iscrtava se ovako:

pogledajte Сл. 2.24

Ovo je preferirani način upućivanja na slike.

Белешка

Da bi :numref: radilo, slika mora imati natpis.

Umesto :numref: moguće je koristiti :ref: za referencu, ali to vraća pun natpis slike.

see :ref:`figure_logo`

iscrtava se ovako:

pogledajte Natpis: Logo koji volim

2.1.7. Tabele

Jednostavnu tabelu možete napraviti ovako:

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

Iscrtaće se ovako:

x

y

z

1

2

3

4

5

Tabele treba da imaju natpis. Možete koristiti eksplicitnu reST direktivu „table“ da biste dodali natpis jednostavnim tabelama ili tabelama sa mrežom. Dodajte natpis u istom redu kao direktivu i uvucite tabelu bar jedan razmak.

Takođe možete dodati cilj hiperlinka pre tabele da biste je negde drugde referencirali. Da biste izbegli sukobe sa drugim referencama, ciljeve hiperlinka uvek počinjite sa _table_ i koristite termine relevantne za natpis tabele.

Evo primera složenije tabele sa mrežom, sa natpisom i ciljem hiperlinka:

.. _table-grid-caption:

.. table:: Grid table with caption

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

Rezultat:

Табела 2.2 Tabela sa mrežom, sa natpisom

Windows

macOS

win

osx

i naravno da ne zaboravimo nix

Možda će vam biti lakše da koristite list tabele ili CSV tabele za pravljenje složenih tabela. Dodajte natpis posle direktive list-table ili csv-table.

Evo primera list tabele sa natpisom i ciljem hiperlinka:

.. _table-list-caption:

.. list-table:: List table with caption
   :header-rows: 1
   :widths: 20 20 20 40

   * - What
     - Purpose
     - Key word
     - Description
   * - **Test**
     - ``Useful test``
     - complexity
     - Geometry.  One of:

       * Point
       * Line

Rezultat:

Табела 2.3 List tabela sa natpisom

Šta

Svrha

Ključna reč

Opis

Test

Koristan test

složenost

Geometrija. Jedno od:

  • Tačka

  • Linija

Koristite uloge :numref: za upućivanje na tabele ovako:

see :numref:`table-grid-caption` or :numref:`table-list-caption`

Rezultat:

Белешка

Morate dodati natpis svojoj tabeli da biste napravili unakrsnu referencu pomoću uloge :numref:.

2.1.8. Index

Indeks je zgodan način da se čitaocu pomogne da pronađe informacije u dokumentu. QGIS dokumentacija pruža neke suštinske indekse. Postoji nekoliko pravila koja nam pomažu da pružimo skup indeksa koji su zaista korisni (koherentni, dosledni i zaista međusobno povezani):

  • Indeks treba da bude čitljiv, razumljiv i prevodiv; indeks se može sastojati od više reči, ali treba da izbegavate sve nepotrebne znakove _, -… za njihovo povezivanje, tj. Loading layers umesto loading_layers ili loadingLayers.

  • Velikim slovom pišite samo prvo slovo indeksa, osim ako reč ima poseban način pisanja. Npr. Loading layers, Atlas generation, WMS, pgsql2shp.

  • Obratite pažnju na postojeću listu indeksa da biste ponovo iskoristili najpogodniji izraz sa ispravnim pisanjem i izbegli nepotrebne duplikate.

U reST-u postoji nekoliko oznaka indeksa. Možete koristiti ugrađenu oznaku :index: unutar običnog teksta:

QGIS can load several :index:`Vector formats` supported by GDAL ...

Ili možete koristiti markup na nivou bloka .. index:: koji vodi ka početku sledećeg pasusa. Zbog gore pomenutih pravila, preporučuje se korišćenje oznake na nivou bloka:

.. index:: WMS, WFS, Loading layers

Takođe se preporučuje korišćenje parametara indeksa kao što su single, pair i see, radi izgradnje strukturiranije i međusobno povezane tabele indeksa. Za više informacija o pravljenju indeksa pogledajte Generisanje indeksa.

2.1.9. Specijalni komentari

Ponekad ćete možda želeti da istaknete neke tačke opisa, bilo da upozorite, podsetite ili date neke savete korisniku. U QGIS dokumentaciji koristimo reST specijalne direktive kao što su .. warning::, .. seealso::, .. note:: i .. tip::. Ove direktive generišu okvire koji ističu vaše komentare. Za više informacija pogledajte Markup na nivou pasusa. Jasan i odgovarajući naslov je obavezan i za upozorenja i za savete.

.. tip:: **Always use a meaningful title for tips**

   Begin tips with a title that summarizes what it is about. This helps
   users to quickly overview the message you want to give them, and
   decide on its relevance.

2.1.10. Isečci koda

Možda ćete takođe želeti da date primere i umetnete isečke koda. U tom slučaju napišite komentar ispod reda sa umetnutom direktivom ::. Za bolje iscrtavanje, naročito za primenu isticanja boja na kôd prema njegovom jeziku, koristite direktivu code-block, npr. .. code-block:: xml. Više detalja na Prikaz koda.

Белешка

Tekst u specijalnim komentarima biće preveden, ali tekst u okvirima code-block neće biti preveden. Zato držite komentare u blokovima koda što je kraće moguće i izbegavajte komentare nepovezane sa kodom.

2.1.11. Fusnote

Ovo je za pravljenje fusnote (prikazuje se kao primer [1])

blabla [1]_

Što će voditi ka:

2.2. Upravljanje snimcima ekrana

2.2.1. Dodavanje novih snimaka ekrana

Evo nekih saveta za pravljenje novih, lepih snimaka ekrana. Slike treba postaviti u folder slika (img/) koji se nalazi u istom folderu kao .rst datoteka koja ih referencira.

  • Neke pripremljene QGIS projekte koji se koriste za pravljenje snimaka ekrana možete pronaći u folderu ./qgis-projects ovog repozitorijuma. Time se olakšava reprodukcija snimaka ekrana za sledeću verziju QGIS-a. Ovi projekti koriste QGIS uzorne podatke (poznate i kao Alaska skup podataka), koje treba raspakovati i postaviti u isti folder kao repozitorijum QGIS-Documentation.

  • Smanjite prozor na minimalni prostor potreban za prikaz mogućnosti (uzimanje celog ekrana za mali modalni prozor > preterivanje)

  • Što manje zbrke, to bolje (nema potrebe za aktiviranjem svih paleta alatki)

  • Nemojte im menjati veličinu u uređivaču slika; veličina će biti postavljena u .rst datotekama ako je potrebno (smanjivanje dimenzija bez propisnog povećanja rezolucije > ružno)

  • Isecite pozadinu

  • Učinite gornje uglove prozirnim ako pozadina nije bela

  • Postavite rezoluciju veličine štampe na 135 dpi (npr. u GIMP-u smanjite sliku pomoću Image ► Scale Image i postavljanjem „X/Y“ na 135 pixels/in, i izvezite je kroz File ► Export…). Na ovaj način, slike će biti u originalnoj veličini u HTML-u i u dobroj rezoluciji štampe u PDF-u.

    Za paket slika možete koristiti i ImageMagick convert komandu:

    convert -units PixelsPerInch input.png -density 135 output.png

  • Sačuvajte ih kao .png (da biste izbegli .jpeg artefakte)

  • Snimak ekrana treba da prikazuje sadržaj u skladu sa onim što je opisano u tekstu

Савет

Ako ste na Ubuntu-u, možete koristiti sledeću komandu da uklonite funkciju globalnog menija i napravite manje ekrane aplikacije sa menijima:

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

2.2.2. Prevedeni snimci ekrana

Evo nekih dodatnih saveta za one koji žele da naprave snimke ekrana za prevedeni korisnički vodič:

Prevedene slike treba postaviti u folder img/<your_language>/. Koristite isti naziv datoteke kao „originalni“ engleski snimak ekrana.

2.3. Dokumentovanje algoritama obrade

Ako želite da pišete dokumentaciju za algoritme obrade, razmotrite ove smernice:

  • Datoteke pomoći algoritama obrade su deo QGIS korisničkog vodiča, pa koristite isto formatiranje kao korisnički vodič i druga dokumentacija.

  • Dokumentacija svakog algoritma treba da bude postavljena u odgovarajući folder provajdera i datoteku grupe, npr. algoritam Voronoi polygon pripada QGIS provajderu i grupi vectorgeometry. Dakle, ispravna datoteka za dodavanje opisa je: source/docs/user_manual/processing_algs/qgis/vectorgeometry.rst.

    Белешка

    Pre nego što počnete da pišete vodič, proverite da li je algoritam već opisan. U tom slučaju možete poboljšati postojeći opis.

  • Izuzetno je važno da svaki algoritam ima sidro koje odgovara nazivu provajdera + jedinstvenom nazivu samog algoritma. Time se dugmetu Pomoć omogućava da otvori stranicu Pomoć ispravnog odeljka. Sidro treba postaviti iznad naslova, npr. (pogledajte i odeljak Natpisi/reference):

    .. _qgisvoronoipolygons:

Voronoi polygons
----------------

    Da biste saznali naziv algoritma, samo zadržite pokazivač miša iznad algoritma u kutiji sa alatkama za obradu.

  • Pomenite QGIS verziju u kojoj je algoritam uveden:

    ``Added in 3.44``

    Isto tako, pomenite ako algoritam zahteva određenu opcionu zavisnost (i verziju).

    .. attention:: Running this algorithm requires QGIS installed with <library> >= min_value
 (see :menuselection:`Help --> About` menu).

  • Izbegavajte korišćenje „Ovaj algoritam radi to i to…“ kao prve rečenice u opisu algoritma. Pokušajte da koristite opštije izraze kao što su:

    Takes a point layer and generates a polygon layer containing the...

  • Izbegavajte opisivanje onoga što algoritam radi ponavljanjem njegovog naziva i nemojte ponavljati naziv parametra u opisu samog parametra. Na primer, ako je algoritam Voronoi polygon, razmotrite da opišete Input layer kao Sloj iz kojeg se računa poligon.

  • U opisu navedite da li algoritam ima podrazumevanu prečicu u QGIS-u ili podržava izmenu na licu mesta.

  • Dodajte slike! Slika vredi hiljadu reči! Koristite .png format i pratite opšte smernice za dokumentaciju (za više informacija pogledajte odeljak Slike i ilustracije). Stavite datoteku slike u ispravan folder, tj. folder img pored .rst datoteke koju menjate.

  • Ako je potrebno, dodajte linkove u odeljak „Pogledajte i“ koji pružaju dodatne informacije o algoritmu (npr. publikacije ili veb stranice). Dodajte odeljak „Pogledajte i“ samo ako zaista ima šta da se vidi. Kao dobra praksa, odeljak „Pogledajte i“ može se popuniti linkovima ka sličnim algoritmima.

  • Dajte jasno objašnjenje za parametre i izlaze algoritma: inspirišite se postojećim algoritmima.

  • Izbegavajte dupliranje detaljnog opisa opcija algoritma. Dodajte ovu informaciju u opis parametra.

  • Izbegavajte dodavanje informacija o tipu vektorske geometrije u opis algoritma ili parametra, pošto je ova informacija već dostupna u opisima parametara.

  • Dodajte podrazumevanu vrednost parametra, npr.:

    * - **Number of points**
  - ``NUMBER_OF_POINTS``
  - [numeric: integer]

    Default: 1
  - Number of points to create

  • Kada se parametar ili vrednost parametra doda već postojećem algoritmu, navedite QGIS verziju u kojoj je uveden. Ako zahteva određenu biblioteku, navedite i njene minimalne zahteve.

  • Opišite tip ulaza koji parametri podržavaju. Dostupno je nekoliko tipova, možete izabrati jedan od:

    Tip parametra/izlaza

    Opis

    Vizuelni pokazatelj

    Tačkasti vektorski sloj

    vector: point

    pointLayer

    Linijski vektorski sloj

    vector: line

    lineLayer

    Poligonski vektorski sloj

    vector: polygon

    polygonLayer

    Svi prostorni vektorski slojevi

    vector: geometry

    Vektorski sloj bez geometrije

    vector: table

    tableLayer

    Generički vektorski sloj

    vector: any

    Numeričko vektorsko polje

    tablefield: numeric

    fieldFloat

    Niskovno vektorsko polje

    tablefield: string

    fieldText

    Generičko vektorsko polje

    tablefield: any

    Rasterski sloj

    raster

    rasterLayer

    Rasterski kanal

    raster band

    HTML datoteka

    html

    Expression

    expression

    expression

    Linijska geometrija

    geometry: line

    Tačkasta geometrija

    coordinates

    Obuhvat

    extent

    CRS

    crs

    setProjection

    Nabrajanje

    enumeration

    selectString

    Lista

    list

    Celobrojna vrednost

    numeric: integer

    selectNumber

    Decimalna vrednost

    numeric: double

    selectNumber

    Niska

    string

    inputText

    Logička vrednost

    boolean

    checkbox

    Putanja foldera

    folder

    Datoteka

    file

    Matrica

    matrix

    Sloj

    layer

    Isti tip izlaza kao tip ulaza

    same as input

    Definition

    definition

    Slojevi karte

    layer list

    Opseg

    range

    AuthConfig

    authconfig

    Mesh

    mesh

    Raspored

    layout

    LayoutItem

    layoutitem

    Boja

    color

    Razmera

    scale

    Tema karte

    map theme

  • Proučite postojeći i dobro dokumentovan algoritam i kopirajte sve korisne rasporede.

  • Kada završite, samo pratite smernice opisane u A Step By Step Contribution da biste komitovali svoje izmene i napravili Pull Request

Evo primera postojećeg algoritma koji će vam pomoći sa rasporedom i opisom:

.. _qgiscountpointsinpolygon:

Count points in polygon
-----------------------
Takes a point and a polygon layer and counts the number of points from the
point layer in each of the polygons of the polygon layer.
A new polygon layer is generated, with the exact same content as the input
polygon layer, but containing an additional field with the points count
corresponding to each polygon.

.. figure:: img/count_points_polygon.png
  :align: center

  The labels in the polygons show the point count

An optional weight field can be used to assign weights to each point.
Alternatively, a unique class field can be specified. If both options
are used, the weight field will take precedence and the unique class field
will be ignored.

``Default menu``: :menuselection:`Vector --> Analysis Tools`

Parameters
..........

.. list-table::
   :header-rows: 1
   :widths: 20 20 20 40
   :class: longtable

   * - Label
     - Name
     - Type
     - Description
   * - **Polygons**
     - ``POLYGONS``
     - [vector: polygon]
     - Polygon layer whose features are associated with the count of
       points they contain
   * - **Points**
     - ``POINTS``
     - [vector: point]
     - Point layer with features to count
   * - **Weight field**

       Optional
     - ``WEIGHT``
     - [tablefield: numeric]
     - A field from the point layer.
       The count generated will be the sum of the weight field of the
       points contained by the polygon.
   * - **Class field**

       Optional
     - ``CLASSFIELD``
     - [tablefield: any]
     - Points are classified based on the selected attribute and if
       several points with the same attribute value are within the
       polygon, only one of them is counted.
       The final count of the points in a polygon is, therefore, the
       count of different classes that are found in it.
   * - **Count field name**
     - ``FIELD``
     - [string]

       Default: 'NUMPOINTS'
     - The name of the field to store the count of points
   * - **Count**
     - ``OUTPUT``
     - [vector: polygon]

       Default: [Create temporary layer]
     - Specification of the output layer type (temporary, file,
       GeoPackage or PostGIS table).
       Encoding can also be specified.

Outputs
.......

.. list-table::
   :header-rows: 1
   :widths: 20 20 20 40

   * - Label
     - Name
     - Type
     - Description
   * - **Count**
     - ``OUTPUT``
     - [vector: polygon]
     - Resulting layer with the attribute table containing the
       new column with the points count