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

2.1. Documentatie schrijven

2.1.1. 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 middel 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
^^^^^^^^^^

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

2.1.3. Inspringen

Inspringen in ReStructuredText zou moeten worden uitgelijnd met de lijst of markup marker. Het is ook mogelijk blokquotes met inspringingen te maken. Bekijk de Specificatie

#. 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. Tags in regels

U kunt tags gebruiken om 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`

  • Titels van dialoogvensters en tabs: Labels die worden weergegeven als een deel van een interactieve gebruikersinterface, inclusief titels van vensters en tabs, knoppen en optielabels.

    :guilabel:`title`

  • Bestandsnamen en mappen

    :file:`README.rst`

  • Pictogrammen met pop-uptekst

    |icon| :sup:`popup_text`

    (zie image hieronder).

  • Keyboard shortcuts

    :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 met als eerste letter een hoofdletter: Esc

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

  • Gebruikerstekst

    ``label``

2.1.5. Labels/verwijzingen

Ankers binnen de tekst kunnen worden gebruikt om hyperlinks naar gedeelten of pagina’s te maken.

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.

Onthoud dat het zal springen naar de regel/ding dat volgt op het ‘anker’. U hoeft geen apostrofs te gebruiken, maar u moet wel lege regels na het anker hebben.

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 een link met het bijschrift zal maken (in dit geval de titel van dit gedeelte!):

bekijk Labels/verwijzingen voor meer informatie.

Dus, verwijzing 1 (my_anchor) en verwijzing 2 (Labels/verwijzingen). Omdat de verwijzing vaak een volledig bijschrift weergeeft, is het niet echt noodzakelijk het woord section 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 en verwijzing voor meer informatie.

2.1.6. Figuren en afbeeldingen

Afbeeldingen

Gebruik, om een afbeelding in te voegen

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

wat teruggeeft

../../_images/logo.png

Vervanging

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: 1 em

en roep het dan aan in uw alinea:

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

This is how the example will be displayed:

Mijn alinea begint hier met een mooi logo nice_logo.

U zult ook de aanroep voor het vervangen van de afbeelding moeten toevoegen aan het bestand dat u hebt gewijzigd, om het mogelijk te maken een voorbeeld van het renderen in GitHub te bekijken, dat zo dicht mogelijk bij het renderen als HTML ligt als mogelijk is. Dat kan worden gedaan door het te kopiëren-plakken vanuit substitutions.txt of door het script scripts/find_set_subst.py uit te voeren.

Notitie

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

Afbeelding

.. _figure_logo:

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

   A caption: A logo I like

The result looks like this:

../../_images/logo.png

Fig. 2.23 Een bijschrift: Een logo dat ik leuk vind

Begin ankers voor afbeeldingen altijd met _figure_ en gebruik termen, die gemakkelijk verbinding leggen met het bijschrift van de afbeelding, om conflicten met andere verwijzingen te vermijden. Hoewel alleen de gecentreerde uitlijning verplicht is voor de afbeelding, staat het u vrij elke andere optie te gebruiken voor afbeeldingen (zoals width, height, scale…), indien nodig.

De scripts zullen een automatisch gegenereerd nummer invoegen vóór het bijschrift van de afbeelding in de gemaakte versies voor HTML en 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).

Naar een afbeelding kan worden verwezen met het verwijzingslabel, zoals dit:

see :numref:`figure_logo`

rendert als dit:

zie Fig. 2.23

Dit is de aanbevolen manier om naar afbeeldingen te verwijzen.

Notitie

For :numref: to work, the figure must have a caption.

Het is mogelijk :ref: als verwijzing te gebruiken in plaats van :numref:, maar dat geeft het volledige bijschrift van de afbeelding terug.

see :ref:`figure_logo`

rendert als dit:

zie Een bijschrift: Een logo dat ik leuk vind

Tabellen

Een eenvoudige tabel kan als volgt worden gecodeerd

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

Het zal renderen zoals dit:

x

y

z

1

2

3

4

5

Gebruik een \ (backslash) gevolgd door een lege spatie om een lege spatie te laten.

U kunt ook meer gecompliceerde tabellen maken en naar ze verwijzen:

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

Voor nog meer complexere tabellen is het gemakkelijker om list-table te gebruiken:

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

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

       * Point
       * Line

Het resultaat:

Wat

Doel

Sleutelwoord

Beschrijving

Test

Nuttige test

complexiteit

Geometrie. Één van:

  • Punt

  • Lijn

2.1.7. Index

Een index is een handige manier om de lezer te helpen informatie te zoeken in een document. Documentatie voor QGIS verschaft enkele essentiële indices. Er zijn een aantal regels die ons helpen een set indices te verschaffen die echt nuttig zijn (samenhangend, 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 alleen de eerste letter van de index een hoofdletter, tenzij het woord een bijzondere spelling heeft. Bijv. Lagen laden, Atlas genereren, WMS, pgsql2shp.

  • Houd een oogje op de bestaande Index list om de meest passende uitdrukking met de juiste spelling opnieuw te gebruiken en onnodige duplicaten te vermijden.

Verscheidene tags voor indexen bestaan in RST. U kunt de inregelige tag :index: gebruiken in normale tekst:

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

Of u kunt de block-level markup .. index:: gebruiken, die linkt naar het begin van de volgende alinea. Vanwege de hierboven vermelde regels wordt aanbevolen de block-level tag te gebruiken:

.. index:: WMS, WFS, Loading layers

Ook wordt aanbevolen parameters voor de index te gebruiken, zoals single, pair en see, om een meer gestructureerde en onderling verbonden tabel voor de index te bouwen. Zie Index generating voor meer informatie over het maken van een index.

2.1.8. Speciale opmerkingen

Soms wilt u misschien enkele punten van de beschrijving benadrukken, ofwel om te waarschuwen, te herinneren of de gebruiker een hint te geven. In QGIS Documentation gebruiken we reST speciale directieven, zoals .. warning::, .. seealso::`, ``.. note:: en .. tip::. Deze directieven maken frames die uw opmerkingen accentueren. Bekijk Paragraph Level markup voor meer informatie. Een heldere en van toepassing zijnde 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.

2.1.9. Codesnippers

U wilt misschien ook voorbeelden geven en codesnippers invoegen. Schrijf, in dat geval, de opmerking onder een regel met de ingevoegde directief ::. Gebruik, voor beter renderen, speciaal om accenten in kleur toe te passen overeenkomstig de taal, het code-block directive, 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 voor codeblokken geen vertaling toestaan. Vermijd dus opmerkingen die niet gerelateerd zijn aan de code en houd opmerkingen zo kort mogelijk.

2.1.10. Voetnoten

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

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

blabla [1]_

Die zal wijzen naar:

2.2. Schermafdrukken beheren

2.2.1. Nieuwe schermafdrukken toevoegen

Hier zijn enkele hints om nieuwe, goed uitziende schermafdrukken te maken. De afbeeldingen zouden moeten worden geplaatst in een map voor afbeeldingen image (img/), die is geplaatst in dezelfde map als waar het betreffende bestand .rst staat.

  • 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 zou moeten 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 (om .jpeg-artefacten te voorkomen)

  • 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

2.2.2. Vertaalde schermafdrukken

Hier zijn enkele aanvullende hints voor hen die schermafdrukken willen maken voor een vertaalde gebruikershandleiding:

Vertaalde afbeeldingen zouden moeten worden geplaatst in een map img/<your_language>/. Gebruik dezelfde naam als de Engelse ‘originele’ schermafdruk.

2.3. Algoritmes voor Processing documenteren

Als u documentatie wilt schrijven voor algoritmes van Processing, denk dan aan deze richtlijnen:

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

  • Elke documentatie voor een algoritme zou moeten worden geplaatst in de overeenkomstige map provider en bestand van de group, bijv. het algoritme Voronoi polygon behoort tot de provider QGIS en de groep vectorgeometry. Dus is het juiste bestand om de beschrijving aan toe te voegen: 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 buitengewoon belangrijk dat elk algoritme een anker heeft dat correspondeert met de naam van de provider + de unieke naam van het algoritme zelf. Dat stelt de knop Help in staat om de pagina Help van het juiste gedeelte te openen. Het anker zou moeten worden geplaatst boven de titel, bijv. (zie ook het gedeelte Labels/verwijzingen):

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

  • Vermijd het gebruiken van “Dit algoritme doet dit en dat…” als de eerste zin in de beschrijving van het algoritme. Probeer meer algemene uitdrukkingen te gebruiken, zoals:

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

  • Vermijd het beschrijven van wat het algoritme doet door zijn naam te dupliceren en dupliceer ook de naam van de parameter niet in de beschrijving van de parameter zelf. Als bijvoorbeeld het algoritme is Voronoi polygoon, overweeg dan om de Invoerlaag te beschrijven als Laag om de polygoon uit te berekenen.

  • 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 het bestand van de afbeelding in de juiste map, d.i. de map img naast het bestand .rst dat u bewerkt.

  • Voeg, indien nodig, links toe in 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 ook echt iets te zien is. Als een goede praktijk kan het gedeelte “Zie ook” ook worden gevuld met links naar soortgelijke algoritmes.

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

  • Vermijd het dupliceren van gedetailleerde beschrijvingen van opties van het algoritme. Voeg deze informatie toe in de beschrijving van de parameter.

  • Vermijd het toevoegen van informatie over het type geometrie van de vector in het algoritme of beschrijving van de parameter, omdat deze informatie al beschikbaar is in de beschrijvingen van de parameter.

  • Voeg de standaardwaarde van de parameter toe, bijv.:

    * - **Number of points**
  - ``NUMBER_OF_POINTS``
  - [number]

    Default: 1
  - Number of points to create

  • 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

    Bestand

    bestand

    Matrix

    matrix

    Laag

    laag

    Hetzelfde type uitvoer als type invoer

    hetzelfde als invoer

    Definitie

    definition

    Punt

    point

    MultipleLayers

    multipleLayers

    Bereik

    range

    AuthConfig

    authconfig

    Mazen

    mesh

    Lay-out

    layout

    Lay-outItem

    layoutitem

    Kleur

    color

    Schaal

    scale

  • Bestudeer een bestaand en goed gedocumenteerd algoritme, en kopieer alle nuttige lay-outs.

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

Hier is een voorbeeld van een bestaand algoritme om 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

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