2. 写作指南

通常，在为QGIS项目创建REST文档时，请遵循 Python documentation style guidelines 。为方便起见，我们在下面提供了一组编写QGIS文档所依赖的一般规则。

2.1. 编写文档

2.1.1. 标题

与文档的每个网页对应一个 .rst 文件。

用来构建文本结构的部分通过它们的标题来标识，标题下划线(第一级带上划线)。相同级别的标题必须使用相同的字符作为下划线装饰。在QGIS文档中，您应该对章节、章节、小节和小节使用以下样式。

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

Section
=======

Subsection
----------

Minisec
.......

Subminisec
^^^^^^^^^^

2.1.2. 列表

列表对于组织文本很有用。以下是所有榜单共有的一些简单规则：

  • 所有列表项都以大写字母开头

  • 不要在只包含一个简单句子的列表项目后使用标点符号

  • 使用期( . )作为由多个句子或单个复合句组成的列表项目的标点符号

2.1.3. 缩进

ReStructiredText中的缩进应与列表或标记对齐 marker 。也可以使用缩进创建块引号。请参阅 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. 内联标签

您可以使用标签来强调项目。

  • Menu GUI ：标记完整的菜单选择序列，包括选择子菜单和选择特定操作，或此类序列的任何子序列。

    :menuselection:`menu --> submenu`

  • Dialogs and Tab titles ：作为交互式用户界面的一部分呈现的标签，包括窗口标题、选项卡标题、按钮和选项标签。

    :guilabel:`title`

  • Filenames and directories

    :file:`README.rst`

  • Icons with popup text

    |icon| :sup:`popup_text`

    (见 image (见下文)。

  • Keyboard shortcuts

    :kbd:`Ctrl+B`

    将会出现 Ctrl+B

    在描述键盘快捷键时，应使用以下约定：

    • 字母键以大写形式显示： S

    • 特殊键以大写首字母显示： Esc

    • 组合键显示为 + 在键之间签名，不带空格： Shift+R

  • User text

    ``label``

2.1.5. 标签/参考文献

文本中的锚点可用于创建指向部分或页面的超链接。

下面的示例创建了一个部分的锚点(例如，标签/引用标题)

.. _my_anchor:

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

若要调用 same page ，使用

see my_anchor_ for more information.

它将返回：

看见 my_anchor 以获取更多信息。

请注意，它将跳到‘锚’之后的行/物。您不需要使用撇号，但在锚点后需要有空行。

跳到同一个地方的另一种方式 from anywhere in the documentation 就是使用 :ref: 角色。

see :ref:`my_anchor` for more information.

它将创建一个带有标题的链接(在本例中是本节的标题！)：

看见 标签/参考文献 以获取更多信息。

所以，参考文献1 (my_anchor) 和参考文献2 (标签/参考文献 )。因为引用通常显示完整的标题，所以实际上没有必要使用该词 section 。请注意，您还可以使用自定义标题来描述引用：

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

它返回：

看见 Label and reference 以获取更多信息。

2.1.6. 数字与图像

图片

要插入图像，请使用

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

它会返回

../../_images/logo.png

更换

您可以将图像放在文本中，也可以添加别名以在任何地方使用。若要在段落中使用图像，请首先在 source/substitutions.txt 文件：

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

然后在你的段落中称其为：

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

以下是该示例的显示方式：

我的段落以一个漂亮的徽标开始 nice_logo 。

要允许在GitHub中尽可能接近于HTML呈现的预览呈现，还需要在更改的文件的末尾添加图像替换调用。这可以通过从以下位置复制粘贴来完成 substitutions.txt 或通过执行 scripts/find_set_subst.py 剧本。

备注

目前，为了确保QGIS图标使用的一致性和帮助，构建了别名列表，并可在 替换 第二章。

插图

.. _figure_logo:

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

   A caption: A logo I like

结果看起来是这样的：

../../_images/logo.png

图 2.23 说明：我喜欢的徽标

为避免与其他引用冲突，地物锚点始终以 _figure_ 并使用容易与插图标题相联系的术语。虽然只有居中对齐对于图像是强制的，但对于插图，您可以随意使用任何其他选项(例如 width ， height ， scale .)如果需要的话。

在生成的HTML和PDF版本的文档中，脚本将在图形标题之前插入一个自动生成的数字。

要使用标题( see My caption )只需在插图块中的空行后插入缩进文本。

可以使用参照标签参照地物，如下所示：

see :numref:`figure_logo`

渲染方式如下：

see 图 2.23

这是引用数字的首选方式。

备注

为 :numref: 为了工作，这个数字 must have a caption 。

它可以使用 :ref: 而不是 :numref: 以供参考，但这将返回图像的完整标题。

see :ref:`figure_logo`

渲染方式如下：

看见 说明：我喜欢的徽标

表格

一个简单的表可以这样编码

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

它将以如下方式渲染：

X

是

Z

1

2

3

4

5

使用 \ (反斜杠)后跟空格以留出空格。

您还可以制作更复杂的表并引用它们：

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

结果是：

窗口

MacOS

赢

OSX

当然，也不要忘记 尼克斯

我画的表，请注意，很遗憾，这不是一个标题

你可以这样引用它 my_drawn_table.

对于更复杂的表，它更易于使用 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

结果是：

什么

目的

关键词

描述

Test

Useful test

复杂性

几何图形。以下选项之一：

  • 点

  • 线

2.1.7. 索引

索引是帮助读者在文档中查找信息的一种便捷方式。QGIS文档提供了一些基本的索引。有几条规则可以帮助我们提供一组真正有用的索引(连贯、一致并真正相互关联)：

  • 索引应该是人类可读、可理解和可翻译的；索引可以由许多单词组成，但应避免任何不必要的内容 _ ， - ..。字符来链接它们，即， Loading layers 而不是 loading_layers 或 loadingLayers 。

  • 除非单词有特定的拼写，否则只将索引的第一个字母大写。例如， Loading layers ， Atlas generation ， WMS ， pgsql2shp 。

  • 关注现有的 Index list 以便重复使用拼写正确的最方便的表达式，避免不必要的重复。

RST中存在几个索引标记。您可以使用内联 :index: 普通文本中的标签：

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

或者，您可以使用 .. index:: 链接到下一段开头的块级标记。基于上述规则，建议使用块级标签：

.. index:: WMS, WFS, Loading layers

还建议使用索引参数，如 single ， pair 和 see ，以构建更加结构化和互联互通的索引表。看见 Index generating 有关创建索引的详细信息，请参阅。

2.1.8. 特别评论

有时，您可能想要强调描述中的一些要点，以警告、提醒或给用户一些提示。在QGIS文档中，我们使用REST特殊指令，例如 .. warning:: ， .. seealso::`, `` 。。注：： `` and ``.. tip::. These directives generate frames that highlight your comments. See Paragraph Level markup 以获取更多信息。警告和提示都需要一个明确和适当的标题。

.. 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. 代码片段

您可能还希望提供示例并插入代码片段。在这种情况下，将注释写在带有 :: 指令已插入。为了获得更好的呈现效果，特别是要根据代码的语言对代码应用颜色突出显示，请使用代码块指令，例如 .. code-block:: xml 。更多详细信息请访问 Showing code 。

备注

虽然笔记、提示和警告框中的文本是可翻译的，但请注意，代码块框不允许翻译。因此，避免使用与代码无关的注释，并尽量保持注释简短。

2.1.10. 脚注

请注意：脚注不能被任何翻译软件识别，也不能正确地转换为pdf格式。因此，如果可能，不要在任何文档中使用脚注。

这是用于创建脚注(以示例形式显示 [1])

blabla [1]_

这将指向：

2.2. 管理屏幕截图

2.2.1. 添加新屏幕截图

这里有一些创建新的、好看的屏幕截图的提示。图像应放置在图像中 (img/ )与引用位于同一文件夹中的文件夹 .rst 文件。

  • 您可以在中找到一些用于创建屏幕截图的已准备好的QGIS项目 ./qgis-projects 此存储库的文件夹。这使得为下一版本的QGIS复制屏幕截图变得更容易。这些项目使用的是QGIS Sample Data (也称为Alaska DataSet)，它应该被解压缩并放置在QGIS-Documentation Repository所在的文件夹中。

  • 将窗口缩小到显示功能所需的最小空间(在整个屏幕上显示一个小的模式窗口>Overkill)

  • 杂乱程度越低越好(无需激活所有工具栏)

  • 不要在图像编辑器中调整它们的大小；大小将设置为 .rst 必要时文件(缩小尺寸而不适当提高分辨率>丑陋)

  • 剪除背景

  • 如果背景不是白色，则使顶角透明

  • 将打印大小分辨率设置为 135 dpi (例如，在GIMP中设置打印分辨率 Image ► Print size 并保存)。这样，图像将在html中保持原始大小，并在PDF中保持良好的打印分辨率。您也可以使用ImageMagick Convert命令来执行一批图像：

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

  • 将它们另存为 .png (为了避免 .jpeg 文物)

  • 屏幕截图应根据文本中描述的内容显示内容

小技巧

如果您使用的是Ubuntu，您可以使用以下命令删除全局菜单功能，并创建带有菜单的较小应用程序屏幕：

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

2.2.2. 翻译的屏幕截图

对于那些想要为翻译后的用户指南创建屏幕截图的人，这里有一些额外的提示：

翻译后的图像应放置在 img/<your_language>/ 文件夹。使用与英文“原始”屏幕截图相同的文件名。

2.3. 记录处理算法

如果您想编写处理算法的文档，请考虑以下指导原则：

  • 处理算法帮助文件是QGIS用户指南的一部分，因此使用与用户指南和其他文档相同的格式。

  • 每个算法文档应放在相应的 provider 文件夹和 group 文件，例如算法 Voronoi polygon 属于 QGIS 提供商和集团 vectorgeometry 。因此，添加描述的正确文件是： source/docs/user_manual/processing_algs/qgis/vectorgeometry.rst 。

    备注

    在开始编写指南之前，请检查是否已经描述了算法。在这种情况下，您可以增强现有的描述。

  • 它是 extremely 重要的是，每个算法都有一个 anchor 这与提供者名称+算法本身的唯一名称相对应。这允许帮助按钮打开正确部分的帮助页面。应该把锚放好 above 标题，例如(另请参阅 标签/参考文献 章节)：

    .. _qgisvoronoipolygons:

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

    要找到算法名称，只需将鼠标悬停在处理工具箱中的算法上。

  • 避免使用“这个算法做这个做那个……”作为算法描述中的第一句话。尝试使用更一般的表达方式，如：：

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

  • 避免通过复制其名称来描述算法的作用，也请不要在参数本身的描述中复制参数的名称。例如，如果算法是 Voronoi polygon 考虑描述一下 Input layer AS Layer to calculate the polygon from 。

  • 在说明中指明算法在QGIS中是否具有默认快捷方式或是否支持在位编辑。

  • 添加图片！一张图片胜过千言万语！使用 .png 格式化并遵循文档的一般指导原则(请参阅 数字与图像 部分了解更多信息)。将图像文件放入正确的文件夹中，即 img 文件夹旁边的 .rst 您正在编辑的文件。

  • 如有必要，在“另见”部分添加链接，提供有关算法的其他信息(例如，出版物或网页)。如果真的有什么可看的，请只添加“See Also”部分。作为一种良好的实践，“See Also”部分可以填充指向类似算法的链接。

  • 对算法参数和输出进行清楚的解释：从现有算法中获得灵感。

  • 避免重复算法选项的详细描述。在参数描述中添加此信息。

  • 避免在算法或参数描述中添加有关矢量几何图形类型的信息，因为该信息已在参数描述中提供。

  • 添加参数的默认值，例如：：

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

    Default: 1
  - Number of points to create

  • 描述一下 type 的输入支持这些参数。您可以从以下几种类型中进行选择：

    参数/输出类型

    描述

    视觉指示器

    点向量层

    vector: point

    点层

    线向量层

    vector: line

    线层

    多边形矢量层

    vector: polygon

    多边形层

    通用矢量层

    vector: any

    向量场数值

    tablefield: numeric

    现场漂浮

    向量场字符串

    tablefield: string

    字段文本

    向量场泛型

    tablefield: any

    栅格层

    raster

    栅格层

    栅格波段

    raster band

    超文本标记语言文件

    html

    表层

    table

    表层

    表达式

    expression

    表达式

    点几何图形

    coordinates

    范围

    extent

    CRS

    crs

    集合投影

    枚举

    enumeration

    选择字符串

    明细表

    list

    数

    number

    选择编号

    细绳

    string

    输入文本

    布尔型

    boolean

    复选框

    文件夹路径

    folder

    档案

    file

    矩阵

    matrix

    图层

    layer

    输出类型与输入类型相同

    same as input

    定义

    definition

    点

    point

    MultipleLayers

    multipleLayers

    射程

    range

    AuthConfig

    authconfig

    网目

    mesh

    布局

    layout

    LayoutItem

    layoutitem

    颜色

    color

    比例尺

    scale

  • 研究一种现有的、有充分记录的算法，并复制所有有用的布局。

  • 完成后，只需遵循中介绍的指导原则 一步一步的贡献 提交您的更改并发出拉入请求

以下是一个示例 existing algorithm 要帮助您进行布局和描述：

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