使用教程

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

问题讨论

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

Fig1-1
图 1: 使用Bizard评论系统讨论问题

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

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

Fig1-2
图 2: 创建 GitHub Discussions

图表征集

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

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

参考示例：新增图表征集（第一期）

Fig2-1
图 3: 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-多组火山图 - 【第一期】Omics/MultiVolcanoPlot

Fig3-1
图 4: GitHub Issues 提交图文教程
Fig3-2
图 5: GitHub Pull Requests 提交图文教程

自动化部署

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

Fig4-1
图 6: GitHub Actions 自动化部署

图库

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

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

Fig5-1
图 7: 图库表格

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

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

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