19. 附录：对本手册的贡献

要向本课程添加材料，您必须遵循本附录中的指导原则。除澄清外，您不得更改本附录中的条件。这是为了确保本手册的质量和一致性得以保持。

19.1. 正在下载资源

这份文件的来源是 GitHub 。会诊 GitHub.com 获取有关如何使用Git版本控制系统的说明。

19.2. 手动格式化

本手册是使用 Sphinx ，这是一个使用 reStructuredText 标记语言。有关如何使用这些工具的说明可在各自的网站上找到。

19.3. 添加模块

要添加新模块，请首先创建一个新目录(直接位于 qgis-training-manual 目录)和新模块的名称。
在这个新目录下，创建一个名为 index.rst 。暂时将此文件留空。

打开 index.rst 顶级目录下的文件。它的第一行是：

.. toctree::
   :maxdepth: 2


   foreword/index
   introduction/index

您会注意到，这是一个目录名的列表，后跟名称 index 。这会将顶级索引文件定向到每个目录中的索引文件。它们的列出顺序决定了它们在文档中的顺序。

添加新模块的名称(即，您为新目录指定的名称)，后跟 /index ，添加到此列表中，无论您希望您的模块出现在哪里。
记住要保持模块的顺序合乎逻辑，这样后面的模块就可以建立在前面模块中提供的知识的基础上。
打开新模块自己的索引文件 ([module name]/index.rst )。
沿着这一页的顶部写一行80个星号 (* )。这代表一个模块标题。
在此之后加上一行包含标记短语的内容 |MOD| (代表“模块”)，后跟模块的名称。
以另一行80个星号结束这个单词。
在这下面留一条空白线。
写一小段话，解释模块的目的和内容。
保留一行空白，然后添加以下文本：
```
.. toctree::
   :maxdepth: 2


   lesson1
   lesson2
```
..。哪里 lesson1 ， lesson2 等等，是你计划上的课的名字。

模块级别的索引文件如下所示：

*******************************************************************************
|MOD| Module Name
*******************************************************************************

Short paragraph describing the module.

.. toctree::
   :maxdepth: 2


   lesson1
   lesson2

19.4. 添加一节课

要向新模块或现有模块添加课程，请执行以下操作：

打开模块目录。
打开 index.rst 文件(如果是新模块，则在上面创建)。
确保计划课程的名称列在 toctree 指令，如上所示。
在模块目录下创建一个新文件。
将此文件命名为与您在模块 index.rst 文件，并添加扩展名 .rst 。

备注

出于编辑目的， .rst 文件的工作方式与普通文本文件完全相同 (.txt )。

要开始编写课程，请编写标记短语 |LS| ，后跟课程名称。
在下一行中，写下一行80个等号 (= )。
在这之后留下一条空闲的线路。
写一段关于本课预期目的的简短描述。
包括对主题的一般介绍。有关示例，请参阅本手册中的现有课程。
在此下方，开始一个新的段落，以以下短语开头：：
```
**The goal for this lesson:**
```
简要解释完成本课的预期结果。
如果你不能用一两句话描述这一课的目标，可以考虑把这个主题分成多节课。

每一课将被细分为多个部分，接下来将讨论这些部分。

19.5. 添加区段

有两种类型的部分：“跟随”和“尝试自己”。

“跟随”部分是一组详细的说明，旨在教读者如何使用QGIS的特定方面。这通常是通过给出尽可能清楚的点击指示，并夹杂着屏幕截图来完成的。
“尝试自己”部分给读者一个简短的任务，让他们自己尝试。它通常与文档结尾处答题纸中的一个条目相关联，该条目将显示或解释如何完成作业，并在可能的情况下显示预期结果。

每一节都有一个难度级别。一个简单的部分由 |basic| ，中位数 |moderate| ，并由 |hard| 。

19.5.1. 添加“跟随”部分

要开始这一节，请编写预期难度级别的标记短语(如上所示)。
留一个空格，然后写下 |FA| (表示“跟随”)。
留出另一个空格，写出部分的名称(只使用首字母大写，专有名词使用大写)。
在下一行中，写下一行80减号/破折号 (- )。确保文本编辑器不会将默认的减号/破折号字符替换为长破折号或其他字符。
对这一部分写一个简短的介绍，解释它的目的。然后就要演示的步骤给出详细的(点击)说明。
在每个部分中，根据需要包括内部链接、外部链接和屏幕截图。
如果可能的话，试着用一小段话来结束每一节，然后自然地通向下一节。

19.5.2. 添加“尝试自己”部分

要开始这一节，请编写预期难度级别的标记短语(如上所示)。
留一个空格，然后写下 |TY| (代表“试一试自己”)。
在下一行中，写下一行80减号/破折号 (- )。确保文本编辑器不会将默认的减号/破折号字符替换为长破折号或其他字符。
解释你希望读者完成的练习。如有必要，请参考前面的章节、课程或模块。
如果简单的文字描述不清楚，则包括屏幕截图以澄清要求。

在大多数情况下，您需要回答如何完成本节中给出的作业。为此，您需要在答题纸中添加一个条目。

首先，为答案确定一个唯一的名称。理想情况下，此名称应包括课程名称和递增数字。

创建此答案的链接：

:ref:`Check your results <answer-name>`

打开答题纸 (answers/answers.rst )。
通过写下这一行，创建一个指向“尝试自己”部分的链接：
```
.. _answer-name:
```
写出关于如何完成作业的说明，在需要的地方使用链接和图片。
要结束它，请写下这一行，包括一个指向“尝试自己”部分的链接：
```
:ref:`Back to text <backlink-answer-name>`
```
要使此链接起作用，请在标题上方将以下行添加到“尝试您自己”部分：
```
.. _backlink-answer-name:
```

请记住，上面显示的每一行的上下都必须有一个空行，否则可能会在创建文档时导致错误。

19.6. 添加结论

要结束一节课，请写下短语 |IC| 表示“在结束时”，后跟一行80减号/破折号 (- )。为本课写一个结论，解释本课涉及的概念。

19.7. 增加一个进一步的阅读部分

此部分是可选的。
写下这个短语 FR 用于“进一步阅读”，后跟80个减号/破折号的新行 (- )。
包括指向相应外部网站的链接。

19.8. 添加下一步是什么部分

写下这个短语 |WN| “What‘s Next”，后面跟着一行新的80减号/破折号 (- )。
解释本课如何使学生为下一课或模块做好准备。
如果有必要，记得更改上一课的“下一课是什么”部分，这样它就可以引用你的新课了。如果在现有课程中或现有课程之后插入了新课程，则需要执行此操作。

19.9. 使用标记

要遵守本文档的标准，您需要在文本中添加标准标记。

19.9.1. 新概念

如果要解释新概念，则需要用星号将新概念的名称用斜体括起来 (* )。
```
This sample text shows how to introduce a *new concept*.
```

19.9.2. 重点

要强调一个不是新概念的关键术语，请用两个星号括起来，用粗体表示 (** )。
少用这个！如果用得太多，读者可能会觉得你在大喊大叫或居高临下。

This sample text shows how to use **emphasis** in a sentence. Include the
punctuation mark if it is followed by a **comma,** or at the **end of the
sentence.**

19.9.3. 图片

添加图像时，请将其保存到文件夹 _static/lesson_name/ 。

将其包含在文档中，如下所示：：

.. figure:: img/image_file.extension
   :align: center

记住在图像标记的上方和下方留出一条空白线。

19.9.4. 内部链接

要为链接创建锚点，请在您希望链接指向的位置上方写下以下行：
```
.. _link-name:
```

要创建链接，请添加以下行：：

:ref:`Descriptive link text <link-name>`

记住在这条线的上方和下方留出一条空白线。

19.9.5. 外部链接

要创建外部链接，请将其写为：：
```
`Descriptive link text <link-url>`_
```
记住在这条线的上方和下方留出一条空白线。

19.9.6. 使用等间距文本

在编写用户需要输入的文本、路径名或数据库元素的名称(如表名或列名)时，必须使用 monospaced text 。例如：：
```
Enter the following path in the text box: :kbd:`path/to/file`.
```

19.9.7. 标记图形用户界面项目

如果您引用的是一个图形用户界面项，如按钮，则必须将其名称写入 the GUI label format 。例如：：
```
To access this tool, click on the :guilabel:`Tool Name` button.
```
如果您在不要求用户单击按钮的情况下提到工具的名称，这也适用。

19.9.9. 添加备注

你可能需要在课文中加一个注释，解释不容易成为课程流程一部分的额外细节。这是标记：：

[Normal paragraph.]

.. note:: Note text.
   New line within note.

   New paragraph within note.

[Unindented text resumes normal paragraph.]

19.9.10. 添加赞助/署名备注

如果你代表赞助商写新的单元、课程或章节，你必须包括他们选择的一条简短的赞助商信息。这必须通知读者赞助商的名字，并且必须出现在他们赞助的单元、课程或章节的标题下面。然而，这可能不是他们公司的广告。

如果你自愿以你自己的身份，而不是代表赞助商，写一个模块、课程或章节，你可以在你所写的模块、课程或章节的标题下面加上一个作者注解。这必须采用以下形式 This [module/lesson/section] contributed by [author name]. 不增加更多的文字，联系方式等。这些细节将添加在前言的“投稿人”部分，以及您添加的部分(S)的姓名(S)。如果你只做了增强、更正和/或添加，请将自己列为编辑。

19.10. 谢谢!

感谢您对这个项目的贡献！通过这样做，您可以使用户更容易访问QGIS，并为整个QGIS项目增加价值。