20. 附录:对本手册的贡献¶

Docs in progress for 'QGIS testing'. Visit https://docs.qgis.org/3.4 for QGIS 3.4 docs and translations.

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

20.1. 正在下载资源

此文档的来源位于 GitHub . 查阅 GitHub.com 有关如何使用Git版本控制系统的说明。

20.2. 手动格式

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

20.3. 添加模块

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

模块级索引文件如下所示:

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

Short paragraph describing the module.

.. toctree::
   :maxdepth: 2


   lesson1
   lesson2

20.4. 增加教训

要将课程添加到新模块或现有模块,请执行以下操作:

注解

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

每节课将细分为多个部分,下一节将讨论。

20.5. 添加节

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

每个部分都有一个难度级别。一个简单的部分用表示 |basic| 适度 |moderate| ,并由 |hard| .

20.5.1. 添加“跟随”部分

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

20.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:
    

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

20.6. 添加结论

20.7. 添加进一步阅读部分

20.8. 添加下一节内容

20.9. 使用标记

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

20.9.1. 新概念

  • 如果你在解释一个新概念,你需要用斜体写下这个新概念的名字,用星号把它括起来。( *

    This sample text shows how to introduce a *new concept*.
    

20.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.**

20.9.3. 图像

  • 添加图像时,将其保存到文件夹中 _static/lesson_name/ .

  • 将其包含在文档中,如下所示:

    .. image:: img/image_file.extension
       :align: center
    
  • 请记住在图像标记的上方和下方留一行空白。

20.9.6. 使用单空格文本

  • 在编写用户需要输入的文本、路径名或数据库元素的名称(如表或列名称)时,必须将其写入 monospaced text . 例如::

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

20.9.7. 标记GUI项

  • 如果您引用的是一个GUI项,例如一个按钮,则必须将其名称写入 the GUI label format . 例如::

    To access this tool, click on the :guilabel:`Tool Name` button.
    
  • 如果在不要求用户单击按钮的情况下提到工具的名称,这也适用。

20.9.9. 添加注释

  • 您可能需要在文本中添加注释,这将解释一些不容易成为课程流程一部分的额外细节。这是标记:

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

20.9.10. 添加赞助/署名说明

如果您代表赞助商编写新的模块、课程或部分,则必须包含他们选择的简短赞助商消息。这必须通知读者赞助商的名称,并且必须出现在他们赞助的模块、课程或部分的标题下面。但不得为公司作广告。

如果您自愿以自己的身份(而不是代表发起人)编写模块、课程或节,您可以在您编写的模块、课程或节的标题下包含作者注释。这个一定是这样的 This [module/lesson/section] contributed by [author name]. 不要添加其他文本、联系方式等。这些详细信息将与您添加的部分的名称一起添加到前言的“参与者”部分。如果您只做了增强、更正和/或添加,请将自己列为一个编辑器。

20.10. 谢谢您!

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