文件编制指南¶

介绍

QGIS Documentation will be built automatically on the server at 0, 8am, 4pm US/Pacific (Pacific Time). The current status is available at https://docs.qgis.org.

QGIS Documentation is mainly written using the reStructuredText (reST) format syntax, coupled with some scripts from the Sphinx toolset to post-process the HTML output. See http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html or https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html.

通常,在为QGIS项目创建RST文档时,请遵循 Python documentation style guidelines . 下面介绍了在使用REST编写QGIS文档时应遵循的一些一般准则。

如果您正在寻找有关帮助QGIS项目或管理存储库的一般规则,请访问 Get Involved in the QGIS Community .

编写文档

头条新闻

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

用于构造文本的部分通过其标题进行标识,该标题带有下划线(并且在第一个级别的上方加了下划线)。同一级别的标题必须使用相同的字符作为下划线装饰。在QGIS文档中,您应该为章节、小节、小节和miniec使用以下样式。

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

Section
=======

Subsection
----------

Minisec
.......

Subminisec
^^^^^^^^^^

列表

列表对于构造文本很有用。以下是所有列表常见的一些简单规则:

  • 以大写字母开头所有列表项
  • 不要在只包含一个简单句子的列表项后使用标点符号
  • 使用期 . )作为由多个句子或单个复合句组成的列表项的标点符号

内联标签

您可以在文本中使用一些标记来强调某些项。

  • Menu GUI: to mark a complete sequence of menu selections, including selecting submenus and choosing a specific operation, or any subsequence of such a sequence.

    :menuselection:`menu --> submenu`
    
  • Dialog and Tab title: Labels presented as part of an interactive user interface including window title, tab title, button and option labels.

    :guilabel:`title`
    
  • 文件名或目录

    :file:`README.rst`
    
  • 具有属于图标的弹出文本的图标

    |icon| :sup:`popup_text`
    

    (见 image 下面)。

  • 键盘快捷键

    :kbd:`Ctrl+B`
    

    将展示 Ctrl+B

    描述键盘快捷方式时,应使用以下约定:

    • 字母键以大写显示: S
    • 特殊键以大写第一个字母显示: Esc
    • 按键组合显示为 + 在钥匙之间签名,无空格: Shift+R
  • 用户文本

    ``label``
    

标记/引用

引用用于在文本中放置锚定。然后它帮助您创建和调用分区或页面之间的超链接。

下面的示例创建节的锚(例如,标签/引用标题)

.. _my_anchor:

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

调用中的引用 同一页, 使用

see my_anchor_ for more information.

将返回:

更多信息请参见我的锚。

注意它将如何跳到“锚”后面的行/事物。通常,要声明此标签,您不需要使用撇号,但需要在锚之前和之后使用空行。

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

see :ref:`my_anchor` for more information.

它将显示标题(在本例中是该节的标题!):

看见 标记/引用 更多信息。

所以参考1(我的锚定)和参考2( 标记/引用 )因为引用通常显示完整的标题,所以实际上不需要使用该词 部分. 请注意,您也可以使用自定义标题来描述引用

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

返回:

看见 Label and reference 更多信息。

图形和图像

图片

要插入图像,请使用

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

哪些回报

../../_images/logo.png

替换

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

.. |nice_logo| image:: /static/common/logo.png
               :width: 2 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

标题:我喜欢的标志

为了避免可能与其他引用发生冲突,请始终以 _figure_ 更喜欢使用容易引用图片标题的术语。虽然图像只有居中对齐是必需的,但请随意使用其他图形选项(例如 widthheightscale ……如果需要的话。

脚本将在文档生成的PDF版本中的图标题前插入自动生成的数字。

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

可以使用这样的引用标签来引用图。

(see Figure_logo_).

它将显示锚图“标志”。如果需要,可以使用大写。它可以同时使用 .rst 文档,但不在其他文档中。你仍然可以使用 :ref: 用于从其他文件引用的角色,但请记住,这将返回图像的完整标题。

see :ref:`figure_logo`

返回:

看见 标题:我喜欢的标志

桌子

创建简单表

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

使用A \ 然后是一个空的空间,留下一个空的空间。

也可以使用更复杂的表格,方法是使用引用和所有

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

结果:

Windows 马科斯
win osx
当然不要忘记 nix

我画的桌子,注意这不是标题

你可以这样引用我画的桌子。

索引

索引是帮助读者在文档中轻松查找信息的简便方法。QGIS文件提供了一些基本指标。为了保持一组真正有用的索引(一致、一致且真正相互联系),几乎没有什么规则可以遵循:

  • 索引应该是人类可读的、可理解的和可翻译的;索引可以由许多单词组成,但应该避免任何不必要的 _- …链接字符,即, Loading layers 而不是 loading_layersloadingLayers .
  • 始终只将索引的第一个字母大写,除非该单词有特定的拼写,在这种情况下,请继续使用其拼写,例如, Loading layersAtlas generationWMSpgsql2shp .
  • 注意现有的 Index list 为了重新使用拼写正确的最方便的表达式,并避免错误的重复。

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

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

或者你可以使用 .. index:: 块级标记,链接到下一段的开头。由于上述规则,建议使用后一个标签,因为这样更容易实现。

.. index:: WMS, WFS, Loading layers

它还建议使用索引参数,例如 singlepairsee …为了建立一个更加结构化和互联的索引表。见 Index generating 有关创建索引的详细信息。

特别意见

有时,您可能希望强调描述中的一些要点,或者警告、提醒或给用户一些提示。在QGIS文档中,我们使用REST特殊指令,例如 .. warning::.. note::.. tip:: 生成突出显示注释的特定框架。见 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.

代码片段

您可能还需要给出示例并插入代码段。在这种情况下,将注释写在 :: 插入指令。但是,为了更好地渲染,特别是根据代码的语言对代码应用颜色突出显示,请使用代码块指令,例如。 .. code-block:: xml . 更多细节 Showing code .

注解

注释、提示和警告框中的文本是可翻译的,请注意代码块框不允许翻译。因此,请避免与代码示例无关的注释,并根据需要保持这一点。

脚注

请注意:任何翻译软件都无法识别脚注,也无法正确转换为PDF格式。因此,如果可能,不要在任何文档中使用脚注。

这是为了创建脚注(如示例所示 [1]

blabla [1]_

它将指向:

[1]核心插件更新

管理屏幕截图

添加新屏幕截图

下面是一些创建新的、好看的屏幕截图的提示。图像应该放在 img/ 文件夹,与RST文件位于同一文件夹中。

  • 所有屏幕盖的环境相同(操作系统相同,装饰相同,字体大小相同)。我们使用了统一的Ubuntu和默认的“氛围”主题。对于QGIS主窗口和布局的屏幕截图,我们将其设置为在窗口上显示菜单(而不是Unity中的默认菜单)。
  • 将窗口缩小到显示该功能所需的最小空间(将小模式窗口的“全屏显示”>Overkill)
  • 越不杂乱越好(不需要激活所有工具栏)
  • 不要在图像编辑器中调整它们的大小,如有必要,大小将被设置为RST文件(缩小尺寸,而不适当提高分辨率>丑陋)
  • 剪切背景
  • 如果背景不是白色,则使顶角透明
  • 将打印尺寸分辨率设置为135 dpi(例如,在gimp中设置打印分辨率 image ‣ print size 并保存。这样,图像将在HTML中保持原始大小,并且在PDF中具有良好的打印分辨率。您还可以使用imagemagick convert命令执行一批图像:
convert -units PixelsPerInch input.png -density 135 output.png
  • 将它们保存在PNG中(没有jpeg工件)

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

  • 您可以在中找到一些以前用于创建截图的已准备好的QGIS项目。 ./qgis-projects . 这使得为下一个版本的QGIS复制屏幕截图变得更加容易。这些项目使用QGIS Sample Data (又称阿拉斯加数据集),应与QGIS文档存储库放在同一文件夹中。

  • 使用以下命令删除Ubuntu中的全局菜单功能,创建具有菜单的较小应用程序屏幕:

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

翻译屏幕截图

下面是一些为您翻译的用户指南创建屏幕截图的提示。翻译后的图像应放在 img/<your_language>/ 文件夹,与RST文件位于同一文件夹中。

  • 所有屏幕盖的环境相同(相同的操作系统、相同的装饰、相同的字体大小)
  • 使用qgis文档库中包含的qgis项目(在 ./qgis_projects )这些是用来制作手册中的“原始”屏幕截图。QGIS Sample Data (又称阿拉斯加数据集)应与QGIS文档存储库放在同一文件夹中。
  • 与英文“原始”截图大小相同,否则它们会被拉伸并看起来很难看。如果由于较长的UI字符串而需要不同的大小,请不要忘记在语言的第一个代码中更改维度。
  • 与英文“原始”屏幕截图相同的文件名
  • 将窗口缩小到显示该功能所需的最小空间(将所有屏幕显示为一个小模式窗口>过杀)
  • 越不杂乱越好(不需要激活所有工具栏)
  • 不要在图像编辑器中调整它们的大小,大小将被设置为RST文件(缩小尺寸,而不适当提高分辨率>丑陋)
  • 剪切背景
  • 将它们保存在PNG中(没有jpeg工件)
  • 屏幕截图应根据文本中描述的内容显示内容。

记录处理算法

如果要编写处理算法的文档,请考虑以下准则:


下面是一个例子 existing algorithm 要帮助您进行布局和描述,请执行以下操作:

.. _qgiscountpointsinpolygon:

Count points in polygon
-----------------------
Takes a point and a polygon layer and counts the number of points from the
first one in each polygon of the second one.

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

Parameters
..........

``Polygons`` [vector: polygon]
  Polygon layer whose features are associated with the count of points
      they contain.

``Points`` [vector: point]
  Point layer to count features from.

``Weight field`` [tablefield: any]
  Optional

  A field with numeric-like values from the point layer.
  The count generated will be the sum of the weight field for each point
  contained by the polygon.

``Class field`` [tablefield: any]
  Optional

  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`` [string]
  The name of the field to store the count of points

  Default: *NUMPOINTS*

Outputs
.......

``Count`` [vector: polygon]
  Resulting layer with the attribute table containing the new column of
  the points count.