Docs in progress for 'QGIS testing'. Visit https://docs.qgis.org/3.4 for QGIS 3.4 docs and translations.
要向本课程添加材料,您必须遵循本附录中的指南。除澄清外,您不得更改本附录中的条件。这是为了确保本手册的质量和一致性。
此文档的来源位于 GitHub . 查阅 GitHub.com 有关如何使用Git版本控制系统的说明。
本手册使用 Sphinx ,使用 reStructuredText 标记语言。有关如何使用这些工具的说明可在各自的网站上找到。
要添加新模块,首先创建一个新目录(直接位于 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
要将课程添加到新模块或现有模块,请执行以下操作:
index.rst
文件(对于新模块,在上面创建)。toctree
指令,如上所示。index.rst
文件,并添加扩展名 .rst
.注解
出于编辑目的,a .rst
文件的工作方式与普通文本文件完全相同( .txt
)
要开始编写课程,请编写标记短语 |LS|
,后跟课程名称。
在下一行中,写一行80个等号( =
)
在这之后留下一行空白。
简要描述课程的预期目的。
包括对主题的一般介绍。有关示例,请参阅本手册中的现有经验教训。
在这下面,开始一个新的段落,从这个短语开始:
**The goal for this lesson:**
简要说明完成本课的预期结果。
如果你不能用一两句话描述这节课的目标,可以考虑把主题分成多节课。
每节课将细分为多个部分,下一节将讨论。
有两种类型的部分:“跟随”和“尝试自己”。
每个部分都有一个难度级别。一个简单的部分用表示 |basic|
适度 |moderate|
,并由 |hard|
.
|FA|
(用于“跟进”)。-
)确保文本编辑器不会将默认的减号/破折号字符替换为长破折号或其他字符。|TY|
(对于“尝试自己”)。-
)确保文本编辑器不会将默认的减号/破折号字符替换为长破折号或其他字符。在大多数情况下,您将希望提供有关如何完成本节中给出的分配的答案。为此,您需要在答题表中添加一个条目。
首先,确定答案的唯一名称。理想情况下,此名称将包括课程名称和递增的数字。
为此答案创建链接:
:ref:`Check your results <answer-name>`
打开答题纸( answers/answers.rst
)
通过编写以下行,创建指向“尝试自己”部分的链接:
.. _answer-name:
写下如何完成任务的说明,必要时使用链接和图像。
要结束它,请写下这一行,包括一个指向“尝试自己”部分的链接:
:ref:`Back to text <backlink-answer-name>`
要使此链接正常工作,请将标题上方的以下行添加到“尝试自己”部分:
.. _backlink-answer-name:
请记住,上面显示的每一行的上面和下面都必须有一个空行,否则在创建文档时可能会导致错误。
|IC|
对于“在结论中”,后面是一行80减/破折号的新行( -
)为本课写一个结论,解释本课涵盖了哪些概念。FR
对于“进一步阅读”,后面是一行80减/破折号的新行。( -
)|WN|
对于“下一步是什么”,后面是一行80减/破折号的新行( -
)要遵守本文档的标准,您需要在文本中添加标准标记。
如果你在解释一个新概念,你需要用斜体写下这个新概念的名字,用星号把它括起来。( *
)
This sample text shows how to introduce a *new concept*.
**
)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.**
添加图像时,将其保存到文件夹中 _static/lesson_name/
.
将其包含在文档中,如下所示:
.. image:: img/image_file.extension
:align: center
请记住在图像标记的上方和下方留一行空白。
要为链接创建锚定,请在链接指向的位置上方写下以下行:
.. _link-name:
若要创建链接,请添加此行:
:ref:`Descriptive link text <link-name>`
记住在这条线的上方和下方留一条线。
要创建外部链接,请按如下方式编写:
`Descriptive link text <link-url>`_
记住在这条线的上方和下方留一条线。
在编写用户需要输入的文本、路径名或数据库元素的名称(如表或列名称)时,必须将其写入 monospaced text
. 例如::
Enter the following path in the text box: :kbd:`path/to/file`.
如果您引用的是一个GUI项,例如一个按钮,则必须将其名称写入 the GUI label format . 例如::
To access this tool, click on the :guilabel:`Tool Name` button.
如果在不要求用户单击按钮的情况下提到工具的名称,这也适用。
您可能需要在文本中添加注释,这将解释一些不容易成为课程流程一部分的额外细节。这是标记:
[Normal paragraph.]
.. note:: Note text.
New line within note.
New paragraph within note.
[Unindented text resumes normal paragraph.]
如果您代表赞助商编写新的模块、课程或部分,则必须包含他们选择的简短赞助商消息。这必须通知读者赞助商的名称,并且必须出现在他们赞助的模块、课程或部分的标题下面。但不得为公司作广告。
如果您自愿以自己的身份(而不是代表发起人)编写模块、课程或节,您可以在您编写的模块、课程或节的标题下包含作者注释。这个一定是这样的 This [module/lesson/section] contributed by [author name].
不要添加其他文本、联系方式等。这些详细信息将与您添加的部分的名称一起添加到前言的“参与者”部分。如果您只做了增强、更正和/或添加,请将自己列为一个编辑器。
感谢您对这个项目的贡献!通过这样做,您可以让用户更容易地访问QGIS,并为整个QGIS项目增加价值。