Viktigt

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

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.

Sections used to structure the text are identified through their title which is underlined (and overlined for the first level). Same level titles must use same character for underline adornment. Precede section titles with a blank line. In QGIS Documentation, you should use following styles for chapter, section, subsection and 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 

Indentation in reStructuredText should be aligned with the list or markup marker. It is also possible to create block quotes with indentation. See the Specification

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

Menyns grafiska gränssnitt: 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``
```
Layers, databases, tables or columns names

When referring to layers, databases, tables or columns, format as inline code:
```
``layer name``
``database_name``
``table_name``
``column_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

Icon substitution 

You can add an image inside a text paragraph (e.g., as a tool icon). To do so, you first need to create an alias (also named substitution), which is a reference name used to display the icon. To ensure consistency across the documents and help in the use of the icons, we maintain a list in the substitutions.txt file at the root of this repository. Find more details in the Substitutioner chapter.

Using an icon substitution is usually achieved through these steps:

Add the icon substitution in the substitutions.txt file as below. If a substitution already exists for the icon you want to use, then skip this step.
```
.. |logo| image:: /static/common/logo.png
   :width: 1 em
```
Call it in your paragraph:
```
My paragraph begins here with |logo|.
```
Add (again) the icon substitution at the end of the file you are modifying. This helps connecting the replacement text with the actual image, and can be done by copy-pasting it from substitutions.txt or by executing the scripts/find_set_subst.py script.

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

My paragraph begins here with .

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:

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 

You can make a simple table like this:

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

Det kommer att återges så här:

x	y	z
1	2	3
4		5

Tables should have a caption. You can use an explicit reST ”table” directive to add a caption to simple tables or grid tables. Add the caption on the same line as the directive and indent the table at least one space.

You can also add a hyperlink target before a table in order to reference it elsewhere. To avoid conflicts with other references, always begin hyperlink targets with _table_ and use terms relevant to the table caption.

Here is an example of a more complicated grid table with a caption and a hyperlink target:

.. _table-grid-caption:

.. table:: Grid table with caption

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

Resultatet blev..:

Table 2.2 Grid table with caption
Windows	macOS

och naturligtvis inte att förglömma

You may find it easier to use list tables or CSV tables to make complex tables. Add the caption after the list-table or csv-table directive.

Here is an example of a list table with a caption and a hyperlink target:

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

Resultatet blev..:

Table 2.3 List table with caption
Vad	Syfte	Nyckelord	Beskrivning
Test	`Nyttigt test`	komplexitet	Geometri. Ett av följande: Punkt Rad

Use :numref: roles to reference tables like this:

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

Resultatet blev..:

see Table 2.2 or Table 2.3

Observera

You must add a caption to your table in order to create a cross reference with the :numref: role.

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.

Several index tags exist in reST. You can use the inline :index: tag within 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

Text in special comments will be translated, but text in code-block frames will not be translated. So keep comments in code blocks as short as possible and avoid comments unrelated to code.

2.1.11. Fotnoter 

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.

You can find some prepared QGIS projects that are used to create screenshots in the ./qgis-projects folder of this repository. This makes it easier to reproduce screenshots for the next version of QGIS. These projects use the QGIS Sample Data (aka Alaska Dataset), which should be unzipped and placed in the same folder as the 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
Set print size resolution to 135 dpi (e.g., in GIMP scale down the image using Image ► Scale Image and setting ”X/Y” to 135 pixels/in, and export it through File ► Export…). This way, images will be at original size in HTML and at a good print resolution in the PDF.

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:

Translated images should be placed in a img/<your_language>/ folder. Use the same filename as the ’original’ English screenshot.

2.3. Dokumentation av bearbetningsalgoritmer 

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

Processing algorithm help files are part of QGIS User Guide, so use the same formatting as the User Guide and other documentation.
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.
It is extremely important that each algorithm has an anchor that corresponds to the provider name + the unique name of the algorithm itself. This allows the Help button to open the Help page of the correct section. The anchor should be placed above the title, e.g. (see also the Etiketter/referenser section):
```
.. _qgisvoronoipolygons:

Voronoi polygons
----------------
```
För att ta reda på algoritmens namn kan du bara hålla muspekaren på algoritmen i verktygslådan Processing.
Avoid using ”This algorithm does this and that…” as the first sentence in the algorithm description. Try to use more general expressions like:
```
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.

Add the default value of the parameter, e.g.:

* - **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`
Linjevektorlager	`vektor: linje`
Polygon vektorlager	`vektor: polygon`
Alla spatiala vektorlager	`vektor: geometri`
Geometrilöst vektorlager	`vektor: tabell`
Generiskt vektorlager	`vektor: valfri`
Vektorfält numerisk	`tabellfält: numerisk`
Vektorfält sträng	`tabellfält: sträng`
Vektorfält generisk	`tabellfält: valfritt`
Ett rasterlager	`raster`
Rasterband	`rasterband`
HTML-fil	`html`
Uttryck	`uttryck`
Line geometry	`geometry: line`
Punktgeometri	`koordinater`
Utsträckning	`extent`
Koordinatsystem	`crs`
Uppräkning	`uppräkning`
Lista	Konfigurationens id %1 finns redan i listan
Heltalsvärde	`numerisk: heltal`
Decimalvärde	`numerisk: dubbel`
Text	`string`
Boolean	`boolean`
Mappens sökväg	`mapp`
Fil	`file`
Matris	`matrix`
Lager	`lager`
Samma utgångstyp som ingångstyp	`same as input`
Definition	`definition`
Kartlager	`lager` `lista`
Intervall	`range`
AuthConfig	`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

Here is an example of an existing algorithm to help you with the layout and the description:

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