贡献者指南¶

Jupyter Book¶

《生物信息学导论》是一部以 MyST Markdown 编写的开源教材，使用 Jupyter Book 2 编译，并通过 GitHub Pages 发布。Jupyter Book 2 目前仍处于 alpha 阶段，以下许多规范可能会有所变动。

规范¶

本教材通篇采用统一规范，旨在使内容结构清晰、便于贡献者理解，并为后续维护与调整提供便利。 以下对这些规范进行详细说明。请参阅 Jupyter Book 2 文档 获取更多信息。

标题与章节¶

本教材使用标题符号（#）来组织结构。每一章应以一个一级标题（#）开头，随后使用二级标题（##）。 如果某一节需要进一步细分，可以使用三级、四级以及最多五级标题（分别为 ###、####、#####）。 但需要注意，子章节将从属于其上方的二级标题，直到遇到下一个二级标题为止。 因此，二级标题应用于引入一个较宽泛的概念，而子章节则提供该概念各具体部分的信息。 每个标题（文末的参考文献部分除外）之后都以分节线（---）结尾。

一个结构规范的 Markdown 文件示例：

# 主标题

章节引言。

---

## 宽泛概念 1

对本节内容的简要概述。

---

### 与概念 1 相关的更具体信息。

具体内容。

---

### 与概念 1 相关的补充具体信息。

具体内容。

---

## 宽泛概念 2

对本节内容的简要概述。

---

## 参考文献

有关标题与章节的更多信息，请参阅 Jupyter Book 文档。

图片¶

当正文需要配图时，使用以下语法：

:::{figure} ../images/image.(png/jpg/svg/etc.)
:alt: 图片的替代文本描述
:align: (center/left/right)
:width: (px/%)
:name: 图片的引用名称

图片的描述说明。
:::

一个规范的图片内容块示例：

:::{figure} images/Week1/aminoacid.jpg
:alt: 氨基酸的结构
:align: center
:width: 40%
:name: aminoacid

氨基酸的结构。四个基团连接在 α-碳原子上：氨基、氢原子、羧基和侧链（R 基团）。
:::

图片描述的末尾应注明适用的许可协议（如有）并引用原始来源。 下一节将介绍如何在正文中添加参考文献并进行引用。 有关图片的更多信息，请参阅 Jupyter Book 文档。

引用、文献引用、许可协议与交叉引用¶

本教材中实现了多种链接方式，每种方式都有其各自的语法要求。以下将逐一详细说明。

引用¶

当需要引用图片时，使用以下语法：

参见 {numref}`图片的引用名称`。

例如，图片内容块如下所示：

:::{figure} images/Week1/protrep.jpg
:alt: 蛋白质表示方法
:align: center
:width: 60%
:name: protrep

使用 NGL 生成的 PDB 结构 5PEP 的不同表示方式。
:::

要在正文中引用该图片，应添加以下内容：

有关示例请参见 {numref}`protrep`。

使用 {numref} 可确保图片自动编号，并在正文中通过该编号进行引用。 有关引用图片的更多信息，请参阅 Jupyter Book 文档。

文献引用与许可协议¶

当使用来自外部来源（论文、网站等）的图片或文字时，必须进行适当的署名标注。

文献引用应使用以下语法在正文中或图片描述末尾进行：

{cite}`引用名称`

引用名称基于仓库根目录下 references.bib 文件中为该引用赋予的名称。 该文件为 BibTeX 文件，包含每个引用的 BibTeX 条目。 BibTeX 引用通常可以直接从论文中下载，但了解其通用格式也很有帮助。 有关 Jupyter Book 2 文献引用的更多信息，请参阅 Jupyter Book 2 文档；有关 BibTeX 引用的通用信息，请参阅 BibTeX.org。

一个包含单条引用的 BibTeX 文件示例：

@article{GDT_2020,
    title = {`It will change everything`: DeepMind's AI makes gigantic leap in solving protein structures},
    author = {Callaway, E.},
    journal = {Nature},
    volume = {588},
    pages = {203-204},
    url = {https://www.nature.com/articles/d41586-020-03348-4},
    doi = {10.1038/d41586-020-03348-4},
    year = {2020}
}

该引用的名称为 GDT_2020。命名的通用格式应遵循 名称_年份 的风格。 在此示例中，GDT 是全局距离测试（global distance test）的缩写，2020 为发表年份。

文献引用应先以 BibTeX 条目的形式添加到 references.bib 文件中，然后才能使用 {cite} 语法。

假设上述示例已保存在 references.bib 中，即可使用以下方式引用：

{cite}`GDT_2020`.

如果所使用的图片有 Creative Commons 许可协议，应在图片描述中注明该许可协议。 许可协议使用以下语法链接至 Creative Commons 网站：

[许可协议类型](许可协议网页链接)

例如，在为图片添加署名时：

:::{figure} images/Week1/terstructure.jpg
:alt: 三级结构相互作用
:align: center
:width: 80%
:name: terstructure

稳定蛋白质三级结构的化学相互作用。
来源：[CC BY 4.0](https://creativecommons.org/licenses/by/4.0) {cite}`proteins_2018`。
:::

这确保了教材中图片的使用不存在任何歧义。文献引用始终位于许可协议之后（如适用）。

瓦赫宁根大学及研究中心（WUR）倾向于将自创图片以 CC BY-NC 4.0 许可协议发布，并使用以下格式：

{cite}`own_[章节编号]_[年份]`.

例如：

{cite}`own_2_2024`. 

用于第 2 章中的自创图片。

有关参考文献与文献引用的更多信息，请参阅 Jupyter Book 文档。

交叉引用¶

有时正文需要引用前面或后面的章节，以帮助读者理解某一主题。 这些即为交叉引用，其使用可以附加到标题上的标签来实现。

创建标题标签的语法如下：

(chapter[#]_label)=

# 标题

交叉引用标签的使用方式为：

[任意文本](#chapter[#]_label)

例如，当需要交叉引用一个关于翻译（translation）的章节时，应在包含翻译信息的标题上方添加以下标签：

(chapter1_translation)=

# Translation

关于翻译的信息。

然后可以使用以下方式进行引用：

有关翻译的更多信息，请参见上述章节 [Translation](#chapter1_translation)。

这将生成一个指向第 1 章 translation 标签的链接，链接文本为 Translation。

有关链接与交叉引用的更多信息，请参阅 Jupyter Book 2 文档。

术语表与术语¶

每一章都有自己的术语表，包含该章最重要的术语及其定义。术语表的创建方式如下：

:::{glossary}
条目 1
: 条目 1 的定义

条目 2
: 条目 2 的定义
:::

条目和定义可以自由创建，但我们同时也使用 {term} 语法直接链接到所有章节术语表中的条目。 这一点很重要，因为 {term} 只能链接到术语表中的精确匹配项（区分大小写）。请看以下示例：

某章的术语表结构如下：

:::{glossary}
MSA
: **M**ultiple **S**equence **A**lignment - 比对两条以上序列的方法。

DNA
: **D**eoxyribo**N**ucleic **A**cid
:::

该章中 MSA 一词的首次出现需要链接到术语表，方式如下：

Instead, in cases where we want to compare 3 or more sequences with each other, we use a **multiple sequence alignment** ({term}`MSA`).

这将创建一个指向术语表中 MSA 条目的直接链接。这不仅适用于本章的术语表条目，如果某术语出现在另一章的术语表中（不允许重复条目），它实际上也会链接到该章的术语表！

只有术语的首次出现才需要添加 {term} 交叉引用（除非你确实想强调之前已在教材中出现过的某个术语的重要性）。 这样做的目的是避免后续章节中出现过多的术语表交叉引用。

参考文献列表¶

每条文献引用都必须包含在参考文献列表中，否则引用将无法生效。 参考文献列表位于每章末尾，仅包含该章中使用过的引用。

在 Markdown 文件末尾添加参考文献列表的方式如下：

## References

:::{bibliography}
:::

这将把所有已使用的引用汇总为页面底部的参考文献列表。

注意：Jupyter Book 2 目前不支持参考文献列表的自定义。使用上述语法将生成标准格式的参考文献列表，无法进一步调整。

注释¶

在编写或审阅 Markdown 文件时，你可能希望为自己或其他贡献者留下注释。 编译器会将每个以 % 开头的行视为注释行。 然而，由于百分号在文本中使用频率较高，这使得筛选注释变得困难，因此推荐使用 %#%[在此处编写你的注释] 的格式来添加注释。 这样可以方便地在 Markdown 文件中搜索注释，并确保注释不会被包含在编译器的实际输出中。 注释应直接放在你想要评论的段落或图片下方。

例如：

#### Secondary structure prediction

As we have seen in Section X.X, there are key similarities and differences between α-helices and β-sheets.
%#%[不确定 Section X.X 指的是哪一节。]

章节编辑与发布¶

由于本教材处于迭代开发阶段，所有贡献者都应了解如何更新和发布各自负责的章节。 仓库使用 GitHub 工作流和 GitHub Actions，完全自动化了教材的部署、发布和上线流程。贡献者可以通过向仓库提交时在提交信息（commit message）中添加特定标记来触发该工作流。

当对某一章进行了修改后，贡献者需要评估此次提交的规模。小范围的更新，如少量修正或改动，应视为补丁更新（patch update）。较大规模的章节修订，可能包括新增或删除小节、新增图片等，应视为次要更新（minor update）。对一章或多章进行全面大改，且影响教材整体结构的，应视为主要更新（major update）。根据上述逻辑做出判断后，提交信息的末尾应添加以下对应的分类标记：

• #patch（这将把教材版本号递增 0.0.1，并触发部署、发布和上线工作流）。
• #minor（这将把教材版本号递增 0.1.0，并触发部署、发布和上线工作流）。
• #major（这将把教材版本号递增 1.0.0，并触发部署、发布和上线工作流）。
• 如果在提交信息末尾省略 #分类 标记，更改将提交到仓库中，但不会触发部署、发布和上线工作流。这在计划连续提交多个更改时非常有用——你不会希望每次提交都重新部署教材。只需确保最后一次提交的提交信息末尾带有 #分类 标记，以便你的更改能够被发布并在教材中可见。

你可以通过访问 GitHub 仓库中的 "Actions" 选项卡来查看工作流的进度。"Deployment" 工作流中的 "Build HTML" 任务会输出潜在的错误或警告信息，贡献者需要修复这些问题，以确保教材正常运行。