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 更多信息。
您可以将图像放在文本中,也可以添加别名以在任何地方使用。要在段落中使用图像,请首先在 source/substitutions.txt
文件:
.. |nice_logo| image:: /static/common/logo.png
:width: 2 em
然后在你的段落中称之为:
My paragraph begins here with a 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
结果如下:
为了避免可能与其他引用发生冲突,请始终以 _figure_
更喜欢使用容易引用图片标题的术语。虽然图像只有居中对齐是必需的,但请随意使用其他图形选项(例如 width
, height
, scale
……如果需要的话。
脚本将在文档生成的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 | 马科斯 |
![]() |
![]() |
当然不要忘记 ![]() |
我画的桌子,注意这不是标题
你可以这样引用我画的桌子。
索引是帮助读者在文档中轻松查找信息的简便方法。QGIS文件提供了一些基本指标。为了保持一组真正有用的索引(一致、一致且真正相互联系),几乎没有什么规则可以遵循:
_
, -
…链接字符,即, Loading layers
而不是 loading_layers
或 loadingLayers
.Loading layers
, Atlas generation
, WMS
, pgsql2shp
.RST中存在多个索引标记。您可以使用内联 :index:
普通文本中的标记。
QGIS allows to load several :index:`Vector formats` supported by GDAL/OGR ...
或者你可以使用 .. index::
块级标记,链接到下一段的开头。由于上述规则,建议使用后一个标签,因为这样更容易实现。
.. index:: WMS, WFS, Loading layers
它还建议使用索引参数,例如 single
, pair
, see
…为了建立一个更加结构化和互联的索引表。见 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 .
注解
注释、提示和警告框中的文本是可翻译的,请注意代码块框不允许翻译。因此,请避免与代码示例无关的注释,并根据需要保持这一点。
下面是一些创建新的、好看的屏幕截图的提示。图像应该放在 img/
文件夹,与RST文件位于同一文件夹中。
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_projects
)这些是用来制作手册中的“原始”屏幕截图。QGIS Sample Data (又称阿拉斯加数据集)应与QGIS文档存储库放在同一文件夹中。如果要编写处理算法的文档,请考虑以下准则:
处理算法帮助文件是QGIS用户指南的一部分,因此使用与用户指南和其他文档相同的格式。
每个算法文档都应该放在相应的 provider 文件夹和 group 文件,例如算法 Voronoi polygon 属于 QGIS 提供者和组 vectorgeometry. 因此添加描述的正确文件是: source/docs/user_manual/processing_algs/qgis/vectorgeometry.rst
.
注解
在开始编写指南之前,检查是否已经描述了算法。在这种情况下,您可以增强现有的描述。
它是 extremely 重要的是每个算法都有一个 anchor 对应于提供程序名称+算法本身的唯一名称。这允许“帮助”按钮将帮助页打开到正确的部分。锚应放置在 above 标题,例如(另请参见 标记/引用 章节):
.. _qgisvoronoipolygons:
Voronoi polygons
----------------
要找到算法名称,只需将鼠标悬停在处理工具箱中的算法上。
避免在算法描述中使用“this algorithm does this and that…”作为第一句话。尝试使用更通用的表达式,如:
Takes a point layer and generates a polygon layer containing the...
避免通过复制算法的名称来描述算法的作用,请不要在参数本身的描述中复制参数的名称。例如,如果算法是 Voronoi polygon
考虑描述 Input layer
喜欢 Layer to calculate the polygon from
.
在描述中指出该算法在qgis中是否有默认快捷方式,或者是否支持就地编辑。
添加图像!一幅画胜过千言万语!使用 .png
格式化并遵循文档的一般指导原则(请参见 图形和图像 更多信息)。将图像文件放入正确的文件夹,即 img
文件夹旁边 .rst
正在编辑的文件。
如有必要,请添加“另见”部分的链接,该部分提供有关算法的其他信息(如出版物或网页)。如果真的有东西要看,只需添加“另见”部分。作为一个好的实践,“另见”部分可以填充到类似算法的链接。
对算法参数和输出给出明确的解释:借鉴现有算法。
避免重复算法选项的详细描述。在参数描述中添加这些信息。
避免在算法或参数描述中添加关于向量几何类型的信息,而无需强制理由,因为该信息已在参数描述中提供。
在中添加参数的默认值 斜体字, 例如。::
``Number of points`` [number]
Number of points to create
Default: *1*
描述 type 的输入支持参数。有几种类型可供选择:
下面是一个例子 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.