Richtlijnen voor schrijven

Volg in het algemeen, bij het maken van documentatie in rst voor het project QGIS, de Python documentation style guide lines. Voor het gemak geven we hieronder een aantal algemene regels waarop wij vertrouwen bij het schrijven van documentatie voor QGIS.

Documentatie schrijven

Kopregels

Elke webpagina van de documentatie komt overeen met een .rst-bestand.

Secties die worden gebruikt om de tekst te structureren worden geïdentificeerd door middle van hun titel die onderstreept is (en met een streep boven voor het eerste niveau). Titels op hetzelfde niveau moeten hetzelfde teken gebruiken voor eenduidig onderstrepen. In QGIS Documentation zou u de volgende stijlen moeten gebruiken voor hoofdstuk, sectie, subsectie en minisec.

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

Section
=======

Subsection
----------

Minisec
.......

Subminisec
^^^^^^^^^^

Lijsten

Lijsten zijn nuttig om structuur aan te brengen in de tekst. Hier zijn enkele eenvoudige regels die voor alle lijsten gelden:

  • Begin alle items van de lijst met een hoofdlettter

  • Gebruik geen punctuatie na items van de lijst die slechts één enkele zin omvatten

  • Gebruik de punt ( . ) als punctuatie voor items van de lijst die bestaan uit meerdere zinnen of één enkele samengestelde zin

Tags in regels

U kunt binnen de tekst enkele tags gebruiken om enkele items te benadrukken.

  • Menu GUI: om een volledige reeks menuselecties te markeren, inclusief het selecteren van submenu’s en het kiezen van een specifieke bewerking, of een subreeks van een dergelijke reeks.

    :menuselection:`menu --> submenu`

  • Titel dialoogvenster en tab: Labels weergegeven als deel van een interactieve gebruikersinterface inclusief titel van het venster, titel van de tab, knop en labels voor opties.

    :guilabel:`title`

  • Bestandsnaam of -map

    :file:`README.rst`

  • Pictogram met pop-uptekst behorende tot het pictogram

    |icon| :sup:`popup_text`

    (zie image hieronder).

  • Snelkoppelingen toetsenbord

    :kbd:`Ctrl+B`

    zal weergeven Ctrl+B

    Bij het beschrijven van snelkoppelingen voor het toetsenbord zouden de volgende conventies moeten worden gebruikt:

    • Toetsen met letters worden weergeven door een hoofdletter: S

    • Speciale toetsen worden weergegeven meet een hoofdletter als eerste letter: Esc

    • Combinaties van toetsen worden weergegeven met een teken + tussen de toetsen, zonder spaties: Shift+R

  • Gebruikerstekst

    ``label``

Label/verwijzing

Verwijzingen worden gebruikt om ankers binnen de tekst te plaatsen. Het helpt u dan om hyperlinks te maken of aan te roepen tussen secties of pagina.

Het voorbeeld hieronder maakt het anker van een sectie (bijv., titel voor label/verwijzing)

.. _my_anchor:

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

Gebruik, om de verwijzing op dezelfde pagina aan te roepen,

see my_anchor_ for more information.

wat terug zal geven:

bekijk my_anchor voor meer informatie.

Bekijk hoe het naar de volgende regel/ding zal springen die volgt op het ‘anker’. Normaal gesproken hoeft u voor het declareren van dit label geen apostroffen te gebruiken, maar dient u lege regels voor en na het anker te gebruiken.

Een andere manier om naar dezelfde plek te springen vanuit ergens in de documentatie is om de rol :ref: te gebruiken.

see :ref:`my_anchor` for more information.

wat in plaats daarvan het bijschrift zal weergeven (in dit geval de titel van deze sectie!):

bekijk Label/verwijzing voor meer informatie.

Dus verwijzing 1 (my_anchor) en verwijzing 2 (Label/verwijzing). Omdat de verwijzing vaak het volledige bijschrift weergeeft, is er niet echt de noodzaak om het woord sectie te gebruiken. Onthoud dat u ook een aangepast bijschrift kunt gebruiken om de verwijzing te beschrijven

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

wat teruggeeft:

bekijk Label and reference Vpor meer informatie.

Figuren en afbeeldingen

Afbeeldingen

gebruik, om een afbeelding in te voegen

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

wat teruggeeft

../../_images/logo.png

Vervangen

U kunt een afbeelding binnen tekst plaatsen of een alias toevoegen om het overal te kunnen gebruiken. Maak eerst een alias in het bestand source/substitutions.txt om een afbeelding binnen een alinea te gebruiken.

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

en roep het dan aan in uw alinea:

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

Dit is hoe het voorbeeld zal worden weergegeven:

Mijn alinea begint hier met een mooi logo nice_logo.

Om in GitHub een voorbeeld te kunnen renderen van de documentatie die het dichtst bij HTML-rendering ligt, dient u ook de aanroep voor het vervangen van de afbeelding toe te voegen aan het einde van het bestand dat u wijzigde. Dat kan worden gedaan door het kopiëren/plakken vanuit substitutions.txt of door het script scripts/find_set_subst.py uit te voeren.

Notitie

Momenteel wordt, om te zorgen voor consistentie en te helpen bij het gebruiken van pictogrammen van QGIS, een lijst met aliassen gebouwd en beschikbaar gemaakt in het hoofdstuk Vervangingen.

Figuur

.. _figure_logo:

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

   A caption: A logo I like

Het resultaat ziet er uit als dit:

../../_images/logo.png

Een bijschrift: Een logo dat ik leuk vind

Begin, om mogelijke conflicten met andere verwijzingen te voorkomen, ankers voor afbeeldingen altijd met _figure_ en gebruik bij voorkeur termen die eenvoudig kunnen verwijzen naar het bijschrift van de afbeelding. Hoewel uitsluitend gecentreerde uitlijning is toegestaan voor de afbeelding, staat het u, indien nodig, vrij andere opties voor afbeeldingen (zoals width, height, scale…) te gebruiken.

De scripts zullen een automatisch gegenereerd nummer invoegen vóór het bijschrift van de afbeelding in de gemaakte versie voor PDF van de documentatie.

Voeg eenvoudigweg ingesprongen tekst in na een lege regel in het blok figure om een bijschrift te gebruiken (zie My caption).

Verwijzen naar de afbeelding kan worden gedaan met behulp van het label verwijzing zoals dit

(see Figure_logo_).

Het zal het anker Figure_logo weergeven. U kunt hoofdletters gebruiken als u dat wilt. Het kan worden gebruikt in hetzelfde .rst-document maar niet in andere. U kunt nog steeds de rol :ref: gebruiken voor verwijzingen vanuit andere bestanden, maar onthoud dat dit het volledige bijschrift van de afbeelding zal teruggeven.

see :ref:`figure_logo`

geeft terug:

zie Een bijschrift: Een logo dat ik leuk vind

Tabellen

Een eenvoudige tabel maken

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

gebruik een \ gevolgd door een lege spatie om een lege spatie te laten.

U kunt ook meer gecompliceerde tabellen maken door ze te tekenen met behulp van verwijzingen en zo

.. _my_drawn_table:

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

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

You can reference to it like this my_drawn_table_.

Het resultaat:

Windows

MacOS

win

osx

en natuurlijk, niet te vergeten, nix

Helaas is voor de door mij getekende tabel geen bijschrift toegelaten

U kunt er op deze manier naar verwijzen my_drawn_table.

Index

Een index is een handige manier om de lezer te helpen om op eenvoudige wijze informatie te zoeken in een document. Documentatie voor QGIS verschaft enkele essentiële indices. Er zijn een aantal regels die moeten worden gevolgd om een set indices te behouden die echt nuttig zijn (coherent, consistent en echt met elkaar verbonden):

  • Een index zou leesbaar moeten zijn voor mensen, begrijpelijk en te vertalen; een index kan uit vele woorden worden gemaakt maar u zou onnodige tekens _, -… moeten vermijden om ze te koppelen, d.i., Laden lagen in plaats van laden_lagen of ladenLagen.

  • Geef altijd alleen de eerste letter van de index een hoofdletter, tenzij het woord een bijzondere spelling heeft, in welk geval het zijn spelling behoudt bijv. Laden lagen`, Atlas genereren, WMS, pgsql2shp.

  • Houd de bestaande Index list in de gaten om de meest nuttige uitdrukking met de juiste spelling opnieuw te gebruiken en verkeerde duplicaten te vermijden.

Er bestaan verscheidene tags voor index in RST. U kunt ofwel de inregelige tag :index: binnen de normale tekst gebruiken.

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

Of u kunt het blokniveau markup .. index:: gebruiken dat koppelt naar het begin van de volgende alinea. Vanwege de hierboven vermelde regels wordt aanbevolen deze laatste tag te gebruiken omdat het eenvoudiger is om daaraan te voldoen.

.. index:: WMS, WFS, Loading layers

Ook wordt aanbevolen om parameters voor een index, zoals single, pair, see…, te gebruiken om een meer gestructureerde en interverbonden indextabel te kunnen maken. Zie Index generating voor meer informatie over het maken van een index.

Speciale opmerkingen

Soms wilt u misschien enkele punten van de beschrijving benadrukken, ofwel om te waarschuwen, als herinnering meegeven of enige hints aan de gebruiker te geven. In de documentatie van QGIS gebruiken we speciale directieven van reST,zoals .. warning::, .. note:: en .. tip:: die bijzondere frames maken die uw opmerkingen accentueren. Zie Paragraph Level markup voor meer informatie. Een heldere en toepasselijke titel is vereist voor zowel waarschuwingen als tips.

.. 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.

Codesnippers

U wilt misschien ook voorbeelden geven en een codesnipper invoegen. Schrijf in dat geval de opmerking onder een regel waarin het directief :: is ingevoegd. Gebruik echter, voor een betere rendering, speciaal bij het toepassen van kleuraccenten overeenkomstig de betreffende taal, het directief code-block, bijv. .. code-block:: xml. Meer details op Showing code.

Notitie

Waar teksten in frames voor opmerkingen, tips en waarschuwingen te vertalen zijn, onthoud dat frames van code blocks geen vertalen toestaan. Vermijd dus opmerkingen die niet zijn gerelateerd aan de voorbeeldcode en houd die zo kort als mogelijk.

Voetnoten

Onthoud: Voetnoten worden niet herkend door enige software voor vertalingen en ze worden ook niet juist geconverteerd naar de indeling PDF. Gebruik dus indien mogelijk geen voetnoten binnen enige documentatie.

Dit is voor het maken van een voetnoot (weergegeven als voorbeeld 1)

blabla [1]_

Die zal wijzen naar:

1

Bijwerken van plug-ins van de bron

Schermafdrukken beheren

Nieuwe schermafdrukken toevoegen

Hier zijn enkele hints voor het maken van nieuwe, goed uitziende schermafdrukken. De afbeeldingen zouden moeten worden geplaatst in de map img/, in dezelfde map als het bestand .rst.

  • Er zijn enkele voorbereide projecten voor QGIS, die worden gebruikt om schermafdrukken te maken, in de map ./qgis-projects van deze opslagplaats. Dit maakt het eenvoudiger om schermafdrukken te reproduceren voor de volgende nieuwe versie van QGIS. Deze projecten gebruiken de QGIS Sample Data (alias Alaska Dataset), die moet worden geplaatst in dezelfde map als de QGIS-Documentation Repository.

  • Verklein het venster naar de minimale ruimte die nodig is om de mogelijkheid weer te geven (het gehele scherm nemen voor een klein modaal venster > overkill)

  • Hoe minder vervuiling, hoe beter (niet nodig om alle werkbalken te activeren)

  • Wijzig de afmetingen niet in een programma voor bewerken van afbeeldingen, de grootte zal in de .rst-bestanden worden ingesteld (verkleinen van de dimensies zonder de resolutie juist omhoog te brengen > lelijk)

  • Snij de achtergrond bij

  • Maak de bovenste hoeken transparant als de achtergrond niet wit is

  • Stel de grootte van de resolutie voor afdrukken in op 135 dpi (bijv. in Gimp instellen van de afdrukresolutie Image ‣ Print size en opslaan). Op deze wijze zullen afbeeldingen met hun originele grootte in HTML staan en met een goede afdrukresolutie in de PDF. U kunt ook de opdracht voor ImageMagick convert gebruiken om een batch met afbeeldingen te verwerken:

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

  • Sla ze op als .png (geen .jpeg artifacten)

  • De schermafdruk zou als inhoud moeten tonen wat overeenkomstig wordt beschreven in de tekst

Tip

Als u Ubuntu gebruikt kunt de volgende opdracht gebruiken om de globale menufunctie te verwijderen en kleinere schermen voor de toepassing te maken met menu’s:

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

Schermafdrukken vertalen

Hier zijn enkele hints voor het maken van nieuwe schermafdrukken voor uw vertaalde gebruikershandleiding. De afbeeldingen zouden moeten worden geplaatst in een map img/<your_language>/ folder, in dezelfde map als het .rst-bestand waarop het betrekking heeft.

  • Gebruik de projecten voor QGIS die zijn opgenomen in de QGIS-Documentation Repository (in ./qgis_projects ). Deze zijn gebruikt voor het maken van de ‘originele’ schermafdrukken in de handleidingen. De QGIS Sample Data (alias Alaska Dataset) dient te worden geplaatst in dezelfde map als de QGIS-Documentation Repository.

  • Dezelfde bestandsnaam als de ‘originele’ Engelse schermafdruk

  • Verklein het venster naar de minimale ruimte die nodig is om de mogelijkheid weer te geven (het gehele scherm nemen voor een klein modaal venster > overkill)

  • Hoe minder vervuiling, hoe beter (niet nodig om alle werkbalken te activeren)

  • Wijzig de afmetingen niet in een programma voor bewerken van afbeeldingen, de grootte zal in de .rst-bestanden worden ingesteld (verkleinen van de dimensies zonder de resolutie juist omhoog te brengen > lelijk)

  • Snij de achtergrond bij

  • Sla ze op als .png (geen .jpeg artifacten)

  • De schermafdruk zou als inhoud moeten tonen wat overeenkomstig wordt beschreven in de tekst

Algoritmen voor Processing documenteren

Neem, bij het schrijven van documentatie voor algoritmen van Processing, de volgende richtlijnen in overweging:

  • De hulpteksten voor algoritmen van Processing zijn onderdeel van de QGIS gebruikershandleiding en gebruiken dus dezelfde opmaak als gebruikershandleiding en andere documentatie.

  • Elke documentatie voor een algoritme zou moten worden geplaatst in de overeenkomstige map provider en bestand group, bijv. het algoritme Voronoi polygon behoort tot de provider QGIS en de groep vectorgeometry. Dus het juiste bestand om de beschrijving aan toe te voegen is dus: source/docs/user_manual/processing_algs/qgis/vectorgeometry.rst.

    Notitie

    Controleer, voor het schrijven naar de handleiding, of het algoritme niet al reeds is beschreven. In dat geval zou u de bestaande beschrijving kunnen uitbreiden.

  • Het is uitermate belangrijk dat elk algoritme een anker heeft dat correspondeert met de naam van de provider + de unieke naam van het algoritme zelf. Dit maakt het voor de knop Help mogelijk om de pagina van de Help voor het juiste gedeelte te openen. Het anker zou moeten wordne geplaatsty boven de titel, bijv. (bekijk ook het gedeelte Label/verwijzing):

    .. _qgisvoronoipolygons:

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

    U hoeft slechts met de muis over het algoritme in de Toolbox van Processing te gaan om de naam van het algoritme te kunnen zien.

  • Voorkom het gebruik van een zin “Dit algoritme doet dit en dat…” als eerste zin in de beschrijving van een algoritme. Probeer meer beeldende zinnen te gebruiken, zoals:

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

  • Vermijd om wat het algoritme doet te beschrijven door het herhalen van de naam en herhal ook de naam van de parameter niet in de beschrijving van de parameter zelf. Als bijvoorbeeld het algoritme is Voronoi polygon, overweeg dan om de Invoerlaag te beschrijven als Laag waaruit de polygoon moet worden berekend.

  • Geef in de beschrijving aan of het algoritme een standaard sneltoets heeft in QGIS of op de plaats bewerken ondersteunt.

  • Voeg afbeeldingen toe! Een afbeelding zegt meer dan duizend woorden! Gebruik de indeling .png en volg de algemene richtlijnen voor documentatie (bekijk het gedeelte Figuren en afbeeldingen voor meer info). Plaats de afbeelding in de juiste map, d.i. de map img naast het bestand .rst dat u bewerkt.

  • Voeg, indien nodig, koppelingen toe naar het gedeelte “Zie ook” dat aanvullende informatie verschaft over het algoritme (bijv. publicaties of webpagina’s). Voeg alleen het gedeelte “Zie ook” toe als er echt iets te zien is. Als een good practice kan het gedeelte “Zie ook” gevuld worden met koppelingen naar soortgelijke algoritmes.

  • Geef duidelijke uitleg over de parameters en de resultaten van algoritmes: haal inspiratie uit bestaande algoritmes.

  • Vermijd een gedetailleerde beschrijving te geven van opties voor het algoritme. Voeg deze informatie toe in de beschrijving van de parameter.

  • Vermijd informatie te geven over de typen geometrie in de beschrijving van algoritme of parameter zonder duidelijke reden, omdat deze informatie al beschikbaar wordt gemaakt in de beschrijving van de parameter.

  • Voeg de standaard waarde van de parameter cursief toe, bijv.:

    ``Number of points`` [number]
  Number of points to create

  Default: *1*

  • Beschrijf het type invoer dat de parameters ondersteunen. Er zijn verschillende types beschikbaar waaruit u kunt kiezen:

    Type parameter/uitvoer

    Beschrijving

    Visuele indicatie

    Puntvectorlaag

    vector: punt

    pointLayer

    Lijnvectorlaag

    vector: lijn

    lineLayer

    Polygoon-vectorlaag

    vector: polygoon

    polygonLayer

    Algemene vectorlaag

    vector: elke

    Numeriek vectorveld

    tabelveld: numeriek

    fieldFloat

    String vectorveld

    tabelveld: string

    fieldText

    Algemeen vectorveld

    tabelveld: elk

    Rasterlaag

    raster

    rasterLayer

    Rasterband

    rasterband

    HTML-bestand

    HTML

    Tabellaag

    tabel

    tableLayer

    Expressie

    expressie

    expression

    Geometrie punt

    coördinaten

    Bereik

    bereik

    CRS

    crs

    setProjection

    Enumeratie

    enumeratie

    selectString

    Lijst

    lijst

    Getal

    getal

    selectNumber

    String

    string

    inputText

    Boolean

    boolean

    checkbox

    Pad map

    map

  • De beste optie is om een bestaand en goed gedocumenteerd algoritme te bestuderen en alle nuttige lay-outs te kopiëren

  • Als het algoritme geen uitvoer geeft, sla dat gedeelte dan over

  • Wanneer u gereed bent, volg dan de richtlijnen die zijn beschreven in Een stap-voor stap bijdrage om uw wijzigingen in te dienen en een Pull Request te maken

Hier is een voorbeeld van een bestaand algoritme o u te helpen met de lay-out en de beschrijving:

.. _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
   :stub-columns: 0

   *  - 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
   :stub-columns: 0

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