Bizard/Tutorial.zh.qmd at main · openbiox/Bizard · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
---
title: 使用教程
---

Bizard 作为一个社区协作的全面可视化代码存储库，基于 GitHub 实现了集**问题讨论**、**图表征集**、**协作开发**、**自动化部署**于一体的平台。社区成员可以通过 `GitHub Discussions` 讨论遇到的困难、通过 `GitHub Issues` 发起新的图表、通过 `GitHub Pull Requests` 参与贡献、通过 `GitHub Action` 自动化部署网站。下面将详细介绍每一步的操作流程：

## 问题讨论

`GitHub Discussions` 是一个类似于论坛的板块，它为项目提供了一个宽松、开放的交流空间。在 Bizard 中，我们基于 giscus 搭建了网站评论系统，位于网站页面的底部：

::: {#fig-Fig2-1}
![](./images/HowToContribute/Discussion-1.png){fig-alt="Fig1-1" fig-align="center" width="90%"}

使用Bizard评论系统讨论问题
:::

如果您在任何图文教程中遇到了问题，可以通过该教程页面底部的评论框发起问题讨论。您需要在评论框先登录您的 GitHub 账号，然后通过 Markdown 语法编辑您的问题。

一旦您提交问题评论，会自动在 Bizard 项目仓库的 `GitHub Discussions` 板块发布您的问题，并标记了图文教程链接。任何社区成员看到您的问题后对可以针对问题进行讨论，Bizard 运营团队也会定期回复 `GitHub Discussions` 中的问题。

::: {#fig-Fig1-2}
![](./images/HowToContribute/Discussion-2.png){fig-alt="Fig1-2" fig-align="center" width="90%"}

创建 GitHub Discussions
:::

## 图表征集

Bizard 长期向社区成员征集新的图表，您可以通过 `GitHub Issues` 进行提交。提交时需要提供以下信息：

- 拟推荐图表名
- 图表分类：Basics / Clinical / Omics
- 图表示例
- 相关资料：图表相关链接

参考示例：[新增图表征集（第一期）](https://github.com/openbiox/Bizard/issues/61)

::: {#fig-Fig2-1}
![](./images/HowToContribute/Issue-1.png){fig-alt="Fig2-1" fig-align="center" width="90%"}

GitHub Issues 征集新的图表
:::

提交 `GitHub Issues` 后，Bizard 运营团队会对图表进行审核，审核结果包括以下三类：

1. 暂不考虑立项
2. 补充到已有的图文教程
3. 新增图文教程

一旦审核通过，您可以通过 `GitHub Issues` 或 `Pull Requests` 提供图文教程。如果您无法提供图文教程，Bizard 运营团队会安排其他人员处理。

## 协作开发

所有社区成员都可以通过 `GitHub Pull Requests` 参与 Bizard 项目的开发，如：贡献新的图文教程、优化网站布局等。

在通过 `Pull Requests` 贡献新的图文教程之前，建议您先提交 `GitHub Issue`。Bizard 运营团队会对图文教程进行审核，并提出一些修改意见。如果您无法提交 `Pull Request`，Bizard 运营团队会安排其他人员提交。

图文教程应按照 Bizard 的格式规范编写，需包含以下内容：

- 图表描述
- 图表示例
- 环境配置
- 数据准备
- 可视化
- 应用场景
- 参考文献

参考示例：
- [【新增图文教程】Omics-多组火山图](https://github.com/openbiox/Bizard/issues/75)
- [【第一期】Omics/MultiVolcanoPlot](https://github.com/openbiox/Bizard/pull/133)

::: {#fig-Fig3-1}
![](./images/HowToContribute/PR-1.png){fig-alt="Fig3-1" fig-align="center" width="90%"}

GitHub Issues 提交图文教程
:::

::: {#fig-Fig3-2}
![](./images/HowToContribute/PR-2.png){fig-alt="Fig3-2" fig-align="center" width="90%"}

GitHub Pull Requests 提交图文教程
:::

## 自动化部署

为了保证网站开发的效率与可靠性，彻底消除手动更新网站所带来的繁琐、延迟及人为错误的风险。Bizard 通过 `GitHub Actions` 构建了一套完备的自动化工作流，实现了从代码提交到线上部署的全程自动化，极大地提升了网站迭代的敏捷性与稳定性。其工作流程为：当开发者将新的网站内容或代码更新推送
（Push）到指定的主分支（如 main 或 master），或发起一个合并请求（Pull Request）时，`GitHub Actions` 将被自动激活。它会立即在 GitHub 提供的纯净虚拟环境中，严格按照预设的配置文件（Workflow
File ）执行一系列关键任务，构建网站并自动化部署到 GitHub Pages 网页。

::: {#fig-Fig4-1}
![](./images/HowToContribute/Action-1.png){fig-alt="Fig4-1" fig-align="center" width="90%"}

GitHub Actions 自动化部署
:::

## 图库

为了解决绘图数量快速增长带来的查找困难、管理混乱、效率低下等问题，Bizard 引入了图库（Graph Gallery）页面。Bizard 利用先进的表格管理工具 [reactable](https://github.com/glin/reactable) 集成了所有绘图信息，并使用 JavaScript 和 CSS 前端代码渲染表格。在这个表格中，每行代表一个图形，包含关键属性：图形ID、名称、描述和类型。用户可以通过筛选、排序和关键词搜索，从庞大的图库中准确找到所需内容，从而显著提高信息检索效率。

我们使用位于 `Bizard/files/` 路径下的中英文两个版本的表格来管理图库，如下所示：

::: {#fig-Fig5-1}
![](./images/HowToContribute/Gallery1.png){fig-alt="Fig5-1" fig-align="center" width="90%"}

图库表格
:::

开发者在更新图库时需要将图形的信息填写到这两个表格中，内容包括：

- `Id`: 图形编号
- `Name`: 图形名称
- `Image_url`: 图形链接，可以复制渲染好的教程中的图形链接
- `Tutorial_url`: 教程链接
- `Description`: 一句话简单描述图形
- `Type`: 图形三级类型
- `Level1`: 图形一级类型，包括：BASICS、OMICS、CLINICS、HIPLOT
- `Level2`: 图形二级类型，如：Distribution、Correlation、Ranking 等

为了保证表格文字能正常渲染，填写完成后需要将表格保存为 **CSV UTF-8** 格式。