Viktigt

Översättning är en gemenskapsinsats du kan gå med i. Den här sidan är för närvarande översatt till 100.00%.

2. Riktlinjer för skrivande

I allmänhet, när du skapar reST-dokumentation för QGIS-projektet, vänligen följ Python documentation style guidelines. För enkelhetens skull tillhandahåller vi en uppsättning allmänna regler som vi förlitar oss på för att skriva QGIS-dokumentation nedan.

2.1. Skriva dokumentation

2.1.1. Rubriker

Till varje webbsida i dokumentationen hör en fil med namnet .rst.

Avdelningar som används för att strukturera texten identifieras genom sin titel som är understruken (och överstruken för den första nivån). Titlar på samma nivå måste använda samma tecken för understrykning. I QGIS Documentation bör du använda följande stilar för kapitel, avsnitt, underavsnitt och minisec.

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

Section
=======

Subsection
----------

Minisec
.......

Subminisec
^^^^^^^^^^

2.1.2. Listor

Listor är användbara för att strukturera texten. Här är några enkla regler som är gemensamma för alla listor:

  • Börja alla listobjekt med en stor bokstav

  • Använd inte skiljetecken efter listobjekt som bara innehåller en enda enkel mening

  • Använd punkt ( .` ) som skiljetecken för listobjekt som består av flera meningar eller en enda sammansatt mening

2.1.3. Indrag

Indrag i ReStructuredText ska vara i linje med listan eller markeringen marker. Det är också möjligt att skapa blockcitat med indrag. Se Specifikation

#. 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. Inline-taggar

Du kan använda taggar för att framhäva objekt.

  • Menu GUI: för att markera en komplett sekvens av menyval, inklusive val av undermenyer och val av en specifik åtgärd, eller en delsekvens av en sådan sekvens.

    :menuselection:`menu --> submenu`

  • Dialog- och fliktitlar: Etiketter som presenteras som en del av ett interaktivt användargränssnitt, inklusive fönstertitlar, fliktitlar, knapp- och alternativetiketter.

    :guilabel:`title`

  • Filnamn och kataloger

    :file:`README.rst`

  • Ikoner med popup-text

    |icon| :sup:`popup_text`

    (se bild nedan).

  • Kortkommandon för tangentbord

    :kbd:`Ctrl+B`

    kommer att visa Ctrl+B

    Vid beskrivning av kortkommandon bör följande konventioner användas:

    • Bokstavsknappar visas med versaler: S

    • Specialknappar visas med en versal första bokstav: Esc

    • Tangentkombinationer visas med tecknet + mellan tangenterna, utan mellanslag: Shift+R

  • Användarens text

    ``label``

  • Namn på lager

    När du hänvisar till lager, formatera som inline-kod:

    ``layer name``

2.1.5. Etiketter/referenser

Ankare i texten kan användas för att skapa hyperlänkar till avsnitt eller sidor.

I exemplet nedan skapas ett ankare för ett avsnitt (t.ex. etikett/referenstitel)

.. _my_anchor:

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

För att ringa upp referensen på samme sida, använd

see my_anchor_ for more information.

som kommer att återvända:

se my_anchor för mer information.

Observera att den kommer att hoppa till raden/det som följer efter ”ankaret”. Du behöver inte använda apostrofer, men du måste ha tomma rader efter ankaret.

Ett annat sätt att hoppa till samma plats från var som helst i dokumentationen är att använda rollen :ref:.

see :ref:`my_anchor` for more information.

vilket skapar en länk med bildtexten istället (i det här fallet titeln på det här avsnittet!):

se Etiketter/referenser för mer information.

Alltså, referens 1 (my_anchor) och referens 2 (Etiketter/referenser). Eftersom referensen ofta visar en fullständig bildtext är det egentligen inte nödvändigt att använda ordet sektion. Observera att du också kan använda en anpassad bildtext för att beskriva referensen:

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

som återvänder:

se Märkning och referens för mer information.

2.1.6. Siffror och bilder

Bilder

Om du vill infoga en bild använder du

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

som returnerar

../../_images/logo.png

Ersättning

Du kan lägga in en bild i texten eller lägga till ett alias för att använda den överallt. Om du vill använda en bild i ett stycke måste du först skapa ett alias i filen source/substitutions.txt:

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

och sedan kalla det i ditt stycke:

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

Det är så här exemplet kommer att visas:

Mitt stycke börjar här med en fin logotyp nice_logo.

För att tillåta förhandsgranskning i GitHub som är så nära HTML-rendering som möjligt måste du också lägga till anropet för bildersättning i slutet av filen du ändrade. Detta kan göras genom att kopiera och klistra in det från substitutions.txt eller genom att köra skriptet scripts/find_set_subst.py.

Observera

För närvarande, för att säkerställa konsekvens och hjälpa till vid användningen av QGIS-ikoner, byggs en lista över alias som finns tillgänglig i kapitlet Substitutioner.

Media

.. _figure_logo:

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

   A caption: A logo I like

Resultatet ser ut så här:

../../_images/logo.png

Fig. 2.24 En bildtext: En logotyp som jag gillar

För att undvika konflikter med andra referenser ska du alltid börja figurankare med _figure_ och använda termer som enkelt kan kopplas till figurtexten. Även om endast centrerad justering är obligatorisk för bilden, får du gärna använda andra alternativ för figurer (t.ex. width, height, scale…) om det behövs.

Skripten kommer att infoga ett automatiskt genererat nummer före bildtexten i den genererade HTML- och PDF-versionen av dokumentationen.

För att använda en bildtext (se Min bildtext) infogar du bara indragen text efter en tom rad i figurblocket.

En figur kan refereras till med hjälp av referensetiketten på följande sätt:

see :numref:`figure_logo`

renderingar så här:

se Fig. 2.24

Detta är det föredragna sättet att referera till figurer.

Observera

För att :numref: ska fungera måste figuren ha en bildtext.

Det är möjligt att använda :ref: i stället för :numref: som referens, men då returneras hela bildtexten.

see :ref:`figure_logo`

renderingar så här:

se En bildtext: En logotyp som jag gillar

2.1.7. Tabeller

En enkel tabell kan kodas så här

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

Det kommer att återges så här:

bredd

Y

z

1

2

3

4

5

Använd en ` (backslash) följt av ett tomt utrymme för att lämna ett tomt utrymme.

Du kan också göra mer komplicerade tabeller och hänvisa till dem:

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

Resultatet blev..:

Fönster

macOS

win

osx

och naturligtvis inte att förglömma nix

Mitt ritbord, märk väl att detta tyvärr inte är att betrakta som en bildtext

Du kan hänvisa till den så här my_drawn_table.

För ännu mer komplexa tabeller är det lättare att använda list-table:

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

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

       * Point
       * Line

Resultatet blev..:

Vad

Syfte

Nyckelord

Beskrivning

Test

Nyttigt test

komplexitet

Geometri. Ett av följande:

  • Punkt

  • Rad

2.1.8. Index

Ett index är ett praktiskt sätt att hjälpa läsaren att hitta information i ett dokument. QGIS-dokumentationen innehåller några viktiga index. Det finns några regler som hjälper oss att tillhandahålla en uppsättning index som är riktigt användbara (sammanhängande, konsekventa och verkligen kopplade till varandra):

  • Ett index ska vara läsbart för människor, förståeligt och översättningsbart; ett index kan göras av många ord men du bör undvika onödiga _, -… tecken för att länka dem, t.ex. Loading layers istället för loading_layers eller loadingLayers.

  • Använd endast stor bokstav på första bokstaven i indexet om inte ordet har en särskild stavning. T.ex. Laddning av lager, Atlasgenerering, WMS, pgsql2shp.

  • Håll ett öga på den befintliga Indexlistan för att kunna återanvända det mest lämpliga uttrycket med rätt stavning och undvika onödiga dubbletter.

Flera index-taggar finns i RST. Du kan använda inline-taggen :index: inom normal text:

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

Eller så kan du använda markeringen .. index:: på blocknivå som länkar till början av nästa stycke. På grund av de regler som nämns ovan rekommenderas det att använda blocknivåtaggen:

.. index:: WMS, WFS, Loading layers

Det är också rekommenderat att använda indexparametrar som ingle, pair och see för att skapa en mer strukturerad och sammankopplad indextabell. Se Indexgenerering för mer information om hur du skapar index.

2.1.9. Särskilda kommentarer

Ibland kanske du vill betona vissa punkter i beskrivningen, antingen för att varna, påminna eller ge några ledtrådar till användaren. I QGIS Documentation använder vi reST-specialdirektiv som ... warning::, ... seealso::, ... note:: och ... tip::. Dessa direktiv genererar ramar som markerar dina kommentarer. Se Paragraph Level markup för mer information. En tydlig och lämplig titel krävs för både varningar och 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.10. Kodsnuttar

Du kanske också vill ge exempel och infoga kodsnuttar. I så fall skriver du kommentaren under en rad med ::-direktivet infogat. För en bättre återgivning, särskilt för att tillämpa färgmarkering på kod enligt dess språk, använd kodblockdirektivet, t.ex. .. code-block:: xml. Mer information finns på Visa kod.

Observera

Texter i ramarna för anmärkningar, tips och varningar kan översättas, men tänk på att ramarna för kodblock inte tillåter översättning. Undvik därför kommentarer som inte är relaterade till koden och håll kommentarerna så korta som möjligt.

2.1.11. Fotnoter

Observera: Fotnoter känns inte igen av något översättningsprogram och konverteras inte heller till pdf-format på rätt sätt. Om möjligt ska du därför inte använda fotnoter i någon dokumentation.

Detta är för att skapa en fotnot (visas som exempel [1])

blabla [1]_

Vilket kommer att peka på:

2.2. Hantera skärmdumpar

2.2.1. Lägg till nya skärmdumpar

Här är några tips för att skapa nya, snygga skärmdumpar. Bilderna ska placeras i en bildmapp (img/) som ligger i samma mapp som den refererande .rst-filen.

  • Du kan hitta några förberedda QGIS-projekt som används för att skapa skärmdumpar i mappen ./qgis-projects i detta arkiv. Detta gör det enklare att reproducera skärmdumpar för nästa version av QGIS. Dessa projekt använder QGIS Sample Data (även kallad Alaska Dataset), som bör packas upp och placeras i samma mapp som QGIS-Documentation Repository.

  • Minska fönstret till det minimala utrymme som behövs för att visa funktionen (ta hela skärmen för ett litet modalt fönster > överdrivet)

  • Ju mindre rörigt, desto bättre (inget behov av att aktivera alla verktygsfält)

  • Ändra inte storlek på dem i en bildredigerare; storleken kommer att ställas in i .rst-filerna om det behövs (nedskalning av dimensionerna utan att öka upplösningen ordentligt > ful)

  • Klipp ut bakgrunden

  • Gör de övre hörnen genomskinliga om bakgrunden inte är vit

  • Ställ in utskriftsstorlekens upplösning till 135 dpi (t.ex. i GIMP, skala ner bilden med hjälp av Image ► Scale Image och ställ in ”X/Y” till 135 pixels/in, och exportera den genom File ► Export…). På så sätt kommer bilderna att vara i originalstorlek i html och ha en bra utskriftsupplösning i PDF-filen.

    Du kan också använda ImageMagick convert-kommandot för att konvertera ett antal bilder:

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

  • Spara dem som .png (för att undvika .jpeg-artefakter)

  • Skärmdumpen ska visa innehållet i enlighet med vad som beskrivs i texten

Tips

Om du använder Ubuntu kan du använda följande kommando för att ta bort den globala menyfunktionen och skapa mindre programskärmar med menyer:

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

2.2.2. Översatta skärmdumpar

Här är några ytterligare tips för dig som vill skapa skärmdumpar för en översatt användarhandbok:

Översatta bilder ska placeras i en img/<ditt_språk>/-mapp. Använd samma filnamn som den engelska ”original”-skärmdumpen.

2.3. Dokumentation av bearbetningsalgoritmer

Om du vill skriva dokumentation för bearbetningsalgoritmer bör du tänka på dessa riktlinjer:

  • Hjälpfiler för bearbetningsalgoritmer är en del av QGIS användarhandbok, så använd samma formatering som användarhandboken och annan dokumentation.

  • Varje algoritmdokumentation ska placeras i motsvarande provider-mapp och group-fil, t.ex. algoritmen Voronoi polygon tillhör QGIS-providern och gruppen vectorgeometry. Så den korrekta filen för att lägga till beskrivningen är: source/docs/user_manual/processing_algs/qgis/vectorgeometry.rst.

    Observera

    Innan du börjar skriva guiden bör du kontrollera om algoritmen redan finns beskriven. I så fall kan du förbättra den befintliga beskrivningen.

  • Det är extremt viktigt att varje algoritm har en ankare som motsvarar leverantörsnamnet + det unika namnet på själva algoritmen. Detta gör att hjälpknappen kan öppna hjälpsidan för rätt avsnitt. Ankaret ska placeras ovanför titeln, t.ex. (se även avsnittet Etiketter/referenser):

    .. _qgisvoronoipolygons:

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

    För att ta reda på algoritmens namn kan du bara hålla muspekaren på algoritmen i verktygslådan Processing.

  • Undvik att använda ”Den här algoritmen gör det här och det där…” som första mening i algoritmbeskrivningen. Försök att använda mer allmänna uttryck som:

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

  • Undvik att beskriva vad algoritmen gör genom att replikera dess namn och replikera inte namnet på parametern i beskrivningen av själva parametern. Till exempel om algoritmen är Voronoi polygon överväga att beskriva Input layer som Layer to calculate the polygon from.

  • Ange i beskrivningen om algoritmen har en standardgenväg i QGIS eller stöd för redigering på plats.

  • Lägg till bilder! En bild säger mer än tusen ord! Använd formatet .png och följ de allmänna riktlinjerna för dokumentation (se avsnittet Siffror och bilder för mer information). Placera bildfilen i rätt mapp, dvs. i mappen img bredvid filen .rst som du redigerar.

  • Om det behövs kan du lägga till länkar i avsnittet ”Se även” som ger ytterligare information om algoritmen (t.ex. publikationer eller webbsidor). Lägg bara till avsnittet ”Se även” om det verkligen finns något att se. Som en god praxis kan avsnittet ”Se även” fyllas med länkar till liknande algoritmer.

  • Ge en tydlig förklaring av algoritmens parametrar och utdata: hämta inspiration från befintliga algoritmer.

  • Undvik att duplicera den detaljerade beskrivningen av algoritmalternativen. Lägg till denna information i parameterbeskrivningen.

  • Undvik att lägga till information om vektorgeometritypen i algoritm- eller parameterbeskrivningen, eftersom denna information redan finns i parameterbeskrivningarna.

  • Lägg till parameterns standardvärde, t.ex.:

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

    Default: 1
  - Number of points to create

  • Beskriv typen av indata som stöder parametrarna. Det finns flera typer tillgängliga som du kan välja en av:

    Parameter/utgångstyp

    Beskrivning

    Visuell indikator

    Punktvektorlager

    vektor: punkt

    pointLayer

    Linjevektorlager

    vektor: linje

    lineLayer

    Polygon vektorlager

    vektor: polygon

    polygonLayer

    Alla rumsliga vektorlager

    vektor: geometri

    Geometrilöst vektorlager

    vektor: tabell

    tableLayer

    Generiskt vektorlager

    vektor: valfri

    Vektorfält numerisk

    tabellfält: numerisk

    fieldFloat

    Vektorfält sträng

    tabellfält: sträng

    fieldText

    Vektorfält generisk

    tabellfält: valfritt

    Ett rasterlager

    raster

    rasterLayer

    Rasterband

    rasterband

    HTML-fil

    html

    Uttryck

    uttryck

    expression

    Punktgeometri

    koordinater

    Utsträckning

    extent

    Koordinatsystem

    crs

    setProjection

    Uppräkning

    uppräkning

    selectString

    Lista

    Konfigurationens id %1 finns redan i listan

    Heltalsvärde

    numerisk: heltal

    selectNumber

    Decimalvärde

    numerisk: dubbel

    selectNumber

    Text

    string

    inputText

    Boolean

    boolean

    checkbox

    Mappens sökväg

    mapp

    Fil

    file

    Matris

    matrix

    Lager

    lager

    Samma utgångstyp som ingångstyp

    Samma som inmatning

    Definition

    definition

    Punkt

    point

    Kartlager

    lager lista

    Intervall

    range

    AuthKonfig

    authconfig

    Nät

    mesh

    Layout

    layout

    LayoutItem

    layoutitem

    Färg

    color

    Skala

    scale

    Karttema

    mapp tema

  • Studera en befintlig och väldokumenterad algoritm och kopiera alla användbara layouter.

  • När du är klar följer du bara de riktlinjer som beskrivs i Ett steg för steg-bidrag för att överföra dina ändringar och göra en Pull Request

Här är ett exempel på en befintlig algoritm för att hjälpa dig med layouten och beskrivningen:

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