Important

翻译是一项社区工作:ref:you can join <translation_guidelines>。此页面目前翻译进度为 100.00%。

19. 附录：为本手册贡献内容

要向本课程添加内容，您必须遵循本附录中的指南。除澄清目的外，不得擅自更改本附录中的条款。这是为了确保本手册的质量与一致性得以维持。

19.1. 下载资源

本文档的源代码托管于 `GitHub <https://github.com/qgis/QGIS-Documentation >`_。有关如何使用 git 版本控制系统的说明，请参阅 `GitHub.com <https://github.com/ >`_。

19.2. 手册格式

本手册使用 Sphinx 编写，这是一个基于 `reStructuredText <https://docutils.sourceforge.io/rst.html >`_ 标记语言的 Python 文档生成器。有关这些工具的使用说明，请参阅其各自官方网站。

19.3. 添加模块

要添加新模块：

1. 首先在 qgis-training-manual 目录的顶层下创建一个新目录，目录名即为新模块的名称。

2. 在此新目录下创建一个名为 index.rst 的文件。暂时留空。

3. 打开顶层目录下的 index.rst 文件。其开头内容如下：

   .. toctree::
      :maxdepth: 2
   
      foreword/index
      introduction/index
   

您会注意到这是一个目录名称列表，每个名称后跟 index。这会将顶层索引文件指向各个目录中的索引文件。列表中的顺序即决定了文档中各模块的排列顺序。

1. 将您的新模块名称（即新目录的名称）后接 /index，添加到此列表中您希望该模块出现的位置。

2. 请注意保持模块顺序的逻辑性，确保后续模块建立在前面模块所介绍的知识基础之上。

3. 打开您的新模块自身的索引文件（module_name/index.rst）。

4. 在页面顶部创建模块标题：

   1. 先写一行星号（*）。

   2. 下一行写上标记短语 Module:，后接您的模块名称。

   3. 再以相同数量的星号结束。

   Note

   上下两行星号的长度不得短于模块标题行。

5. 在此下方留一空行。

6. 撰写一段简短文字，说明该模块的目的和内容。

7. 再留一行空白，然后添加以下内容：

   .. toctree::
      :maxdepth: 2
   
      lesson1
      lesson2
   

   ……其中 lesson1、lesson2 等为计划中各课的名称。

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

*******************************************************************************
Module: Module Name
*******************************************************************************

Short paragraph describing the module.

.. toctree::
   :maxdepth: 2

   lesson1
   lesson2

19.4. 添加课程

要向新模块或已有模块添加课程：

1. 打开模块目录。

2. 打开 index.rst 文件（对于新模块，即上述创建的文件）。

3. 确保计划课程的名称已列在 toctree 指令下方，如上所示。

4. 在模块目录下创建一个新文件。

5. 文件名必须与您在模块的 index.rst 文件中提供的名称完全一致，并加上 .rst 扩展名。

Note

就编辑而言，.rst 文件与普通文本文件（.txt）完全相同。

1. 开始编写课程时，先写标记短语 Lesson，后接课程名称。

2. 下一行写一串等号（=），长度不得短于课程标题。

3. 此后留一空行。

4. 撰写一段简短文字，说明本课程的预期目标。

5. 包含对主题内容的总体介绍。可参阅本手册中的现有课程作为示例。

6. 在此下方另起一段，以如下短语开头：

   **The goal for this lesson:**
   

7. 简要说明完成本课程后的预期成果。

8. 若无法用一两句话描述课程目标，请考虑将主题拆分为多个课程。

每节课程将细分为多个小节，接下来将予以说明。

19.5. 添加小节

小节分为两类：“跟随操作”（follow along）和“自行尝试”（try yourself）。

• “跟随操作”小节是一套详细的操作指南，旨在教导读者如何使用 QGIS 的某项功能。通常通过清晰的逐点击操作说明，并穿插截图来实现。

• “自行尝试”小节则为读者提供一个简短的练习任务。通常会在下方的答案框中提供解答，展示或解释如何完成该任务，并尽可能显示预期结果。

每个小节均标注难度等级：简单为 ★☆☆，中等为 ★★☆，高级为 ★★★。

19.5.1. 添加“跟随操作”小节

1. 开始此小节时，先写上对应的难度等级标记短语（如上所示）。

2. 留一个空格，然后写 Follow Along:。

3. 再留一个空格，写上小节名称（仅首字母和专有名词大写）。

4. 下一行写一串减号/短横线（-），长度不得短于小节标题。

5. 撰写一段简短引言，说明本小节目的，然后给出详细的（逐点击）操作步骤。

6. 每个小节应根据需要包含内部链接、外部链接和截图。

7. 尽量以一段简短结语结束每个小节，并自然过渡到下一小节（若可能）。

19.5.2. 添加“自行尝试”小节

1. 开始此小节时，先写上对应的难度等级标记短语（如上所示）。

2. 留一个空格，然后写 Try Yourself:。

3. 下一行写一串减号/短横线（-），长度不得短于小节标题。

4. 说明您希望读者完成的练习任务。必要时可引用前面的小节、课程或模块。

5. 若纯文字描述不够清晰，请附上截图以明确要求。

大多数情况下，您需要提供完成本小节任务的解答。为此，您需在说明下方创建并填充一个答案块。

1. 首先，创建包含答案的自定义可折叠控件：

   .. admonition:: Answer
      :class: dropdown
   

2. 相对于上方代码块保持缩进，撰写完成任务的操作说明，并在需要处使用链接和图片。

19.6. 添加结论

课程结尾应：

1. 写上短语 In Conclusion，下一行写一串减号/短横线（-）。

2. 撰写课程结论，说明本课程涵盖的概念。

19.7. 添加延伸阅读小节

此小节为可选。

• 写上短语 Further Reading，下一行写一串减号/短横线（-）。

• 包含指向相关外部网站的链接。

19.8. 添加“下一步”小节

1. 写上短语 What's Next?，下一行写一串减号/短横线（-）。

2. 说明本课程如何为学生学习下一课或下一模块做好准备。

3. 如有必要，请修改前一课程的“下一步”小节，使其指向您的新课程。当您在已有课程之间或之后插入新课程时，此操作是必需的。

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

• 添加图片时，请将其保存至课程文件旁的 img 文件夹中。

• 在文档中按如下方式引用：

  .. 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. 使用等宽文本

• 当您编写用户需输入的文本、路径名或数据库元素（如表名、列名）时，必须使用 等宽文本。例如：

  Enter the following path in the text box: ``path/to/file``.
  

19.9.7. 标注 GUI 元素

• 若提及 GUI 元素（如按钮），必须使用 GUI 标签格式。例如：

  To access this tool, click on the :guilabel:`Tool Name` button.
  

• 即使未要求用户点击按钮，仅提及工具名称时，也应遵循此规则。

19.9.8. 菜单选择

• 若引导用户浏览菜单，必须使用 菜单 ► 选项 ► 格式。例如：

  To use the :guilabel:`Tool Name` tool, go to :menuselection:`Plugins -->
  Tool Type --> Tool Name`.
  

19.9.9. 添加注释

• 您可能需要在正文中添加注释，用以说明难以融入课程主体的额外细节。标记语法如下：

  [Normal paragraph.]
  
  .. note:: Note text.
    New line within note.
  
    New paragraph within note.
  
  [Unindented text resumes normal paragraph.]
  

19.9.10. 添加赞助/作者声明

若代表赞助方撰写新模块、课程或小节，必须包含其指定的简短赞助声明。该声明需注明赞助方名称，并置于其所赞助的模块、课程或小节标题下方，但不得包含公司广告内容。

若您以个人身份（非代表赞助方）志愿撰写模块、课程或小节，可在其标题下方添加作者声明，格式必须为：本[模块/课程/小节]由[作者姓名]贡献。 请勿添加其他文字、联系方式等。此类详细信息应列入前言的“贡献者”部分，并注明您所添加的内容。若您仅进行了增强、修正或补充，请将自己列为编辑者。

19.10. 感谢您！

感谢您为本项目做出贡献！您的参与让 QGIS 对用户更加友好，并为整个 QGIS 项目增添了价值。