3. 在《PyQGIS Cookbook》中编写代码

如果您计划添加或更新 《PyQGIS开发人员手册》 ，然后您应该遵循一些规则来启用代码片段的自动测试。

测试非常重要，因为它允许自动检查代码。带有错误的代码片段或使用过时方法的代码将失败，通知将帮助您修复问题。

对于测试，我们使用 Sphinx doctest extension 。有关更多详细信息，请参阅扩展文档。

3.1. 如何编写可测试的代码片段

编写可测试的代码片段与 old 方法。基本上，您需要使用不同的狮身人面像 directive 。

3.1.1. Doctest狮身人面像指令

而不是将代码嵌入 .. code-block:: python 指令(它将自动突出显示代码语法)，您现在需要将其嵌入到 .. testcode:: 。也就是说，不是这样：：

.. code-block:: python

   crs = QgsCoordinateReferenceSystem("EPSG:4326")
   assert crs.isValid()

您现在可以使用以下命令：：

.. testcode::

   crs = QgsCoordinateReferenceSystem("EPSG:4326")
   assert crs.isValid()

在编写了示例代码之后，您应该添加一些 assertion 这将评估代码，并将自动运行。

在上面的示例中，您将创建一个CRS并使用 assert crs.isValid() 你 test 如果它是有效的。如果代码具有错误的python语法或 crs.isValid() 退货 False ，则此代码片段将在测试过程中失败。

要成功运行代码段上的测试，必须导入所有类并声明代码段中使用的任何变量。您可以将它们包含在代码段本身中(在HTML页面中可见)，也可以将它们添加到 .. testsetup:: 指令(隐藏在HTML页面中)。这个 .. testsetup:: 需要放在 .. testcode:: **

.. testsetup::

   from qgis.core import QgsCoordinateReferenceSystem

.. testcode::

   crs = QgsCoordinateReferenceSystem("EPSG:4326")
   assert crs.isValid()

如果代码片段没有创建对象(因此您不能使用类似于 assert object.isValid() )，您可以使用 print() 方法，然后将预期结果添加到 .. testoutput:: 用于比较预期输出的指令：：

.. testcode::

   print("QGIS CRS ID:", crs.srsid())
   print("PostGIS SRID:", crs.postgisSrid())

.. testoutput::

   QGIS CRS ID: 3452
   PostGIS SRID: 4326

默认情况下， .. testoutput:: 显示在HTML输出中。若要对HTML隐藏它，请使用 :hide: 选项：：

.. testoutput::
   :hide:

   QGIS CRS ID: 3452
   PostGIS SRID: 4326

备注

如果代码段包含任何打印语句，则必须添加一个 testoutput 使用预期的输出；否则测试将失败。

3.1.2. 分组测试

对于每个rst文档，都会按顺序测试代码片段，这意味着您可以使用一个 .. testsetup:: 对于以下所有代码片段，以及后面的代码片段将可以访问在文档中前面的代码片段中声明的变量。

或者，您可以使用组来分解不同测试中同一页上的示例。

通过在相应的指令中添加一个或多个组名(用逗号分隔)，可以将代码片段添加到组中：：

.. testcode:: crs_crsfromID [, morenames]

   crs = QgsCoordinateReferenceSystem("EPSG:4326")
   assert crs.isValid()

这个 doctest 将选取每个组片段并独立运行它们。

备注

使用与相关内容有意义的组名。使用类似于<章节>_<子章>的内容，例如：crs_troo，crs_from mwkt。在出现故障的情况下，这将有助于识别故障发生的位置。

如果未声明任何组，则代码段将被添加到名为 default 。如果相反，您使用 * 作为组名，代码片段将在所有测试组中使用，通常用于测试设置：：

.. testsetup:: *

   from qgis.core import QgsCoordinateReferenceSystem

3.2. 如何在本地计算机上测试代码片断

备注

说明适用于Linux系统。

要测试Python代码片段，您需要一个 QGIS 安装。对于这一点，有很多选择。你可以：

  • 使用您的系统 QGIS 安装时使用 Sphinx 在Python虚拟环境中：

    make -f venv.mk doctest

  • 使用手动构建的安装 QGIS 。您需要：

    1. 创建自定义 Makefile 上的扩展 venv.mk 文件，例如 user.mk 包含以下内容的文件：

      # Root installation folder
QGIS_PREFIX_PATH = /home/user/apps/qgis-master

include venv.mk

      或：

      # build output folder
QGIS_PREFIX_PATH = /home/user/dev/QGIS-build-master/output

include venv.mk

    2. 然后，使用它来运行目标 doctest **

      make -f user.mk doctest

  • 运行目标 doctest 在官员内部 QGIS Docker镜像：：

    make -f docker.mk doctest

    您必须安装 Docker 首先，这是因为它使用了一个带有QGIS的docker图像。