概况

本在线文档仓库为海塞姆人工智能团队的开源文档仓库。

• 产品手册
• 在线文档维护

产品手册

在线文档维护

本章节记录本在线文档仓库的维护流程。

• 软件环境初始化
• 自动测试工作流
• 文档的编写
• 文档的格式

软件环境初始化

可选在线维护和本地维护两种方式。

在线维护仅需网页环境即可修改维护，但对 Git 提交（Commit）的修改和文档的测试需依赖仓库持续集成。

本地维护需安装并配置多个软件并拉取仓库到本地，对 Git 提交（Commit）的修改和文档测试更友好。

在线维护

仓库配置

点击我以复刻（Fork）本仓库，选择“Create fork”按钮。

您应看到在您的命名空间中的仓库如 your-user-name/public-docs，其中 your-user-name 为您的 GitHub 用户名。 地址似 https://github.com/your-user-name/public-docs。 下文称做“您的仓库”。

接下来请配置自动测试工作流。

本地维护

软件安装

开始在本地维护前，请确保已安装以下软件：

• Git：

  确保运行 git --version 命令无报错。

• mdBook，选择版本：{{ mdbook-version }}：

  • 使用包管理器安装，如执行 pamac install mdbook。
  • 对应操作系统下载后解压出可执行文件并放到环境变量包含的目录中。

  确保运行 mdbook --version 命令无报错。

• AutoCorrect（可选）：

  • 使用包管理器安装，如执行 pamac install autocorrect-bin。
  • 对应操作系统下载后解压出可执行文件并放到环境变量包含的目录中。

  确保运行 autocorrect --version 命令无报错。

仓库配置

点击我以复刻（Fork）本仓库，选择“Create fork”按钮。

您应看到在您的命名空间中的仓库如 your-user-name/public-docs，其中 your-user-name 为您的 GitHub 用户名。 地址似 https://github.com/your-user-name/public-docs。 下文称做“您的仓库”。

接下来请配置自动测试工作流。

自动测试工作流

下文中“您的仓库”指的是您复刻（Fork）的仓库； 如 your-user-name/public-docs，其中 your-user-name 为您的 GitHub 用户名。

1. 在您的仓库的主页面（Code 页面）中，点击顶栏的 Settings，然后点击左侧的 Actions，选择 General， 确保 Actions permissions 设置为 Allow all actions and reusable workflows； 确保 Workflow permissions 设置为 Read and write permissions。
2. 在您的仓库的主页面（Code 页面）中，点击顶栏的 Actions， 点击页面中部的确认 I understand my workflows, go ahead and enable them。
3. 点击顶栏的 Settings，然后点击左侧的 Pages。 设置 Build and deployment 下的 Source 为 GitHub Actions。

文档的编写

启动编辑器

如果您在软件环境初始化时配置了：

• 在线维护：使用在线编辑器；
• 本地维护：使用拉取仓库并本地编辑。

在线编辑器

在您的仓库的主页面（Code 页面）中，按下键盘上的句号键 .， 或访问 https://github.dev/your-user-name/public-docs 启动网页编辑器进行编辑。

拉取仓库并本地编辑

在终端模拟器或命令行执行：

git clone https://github.com/your-user-name/public-docs.git

即可拉取仓库到本地目录 public-docs。

在该目录下启动您喜好的编辑器（如 VSCode），就可开始编写文档了。

目录结构示例

src/
├── index.md                      # 文档首页
├── SUMMARY.md                    # 目录配置文件
├── products/                     # 产品类
│   ├── index.md
│   ├── videoextensometer/        # 视频引伸计类
│   │   ├── index.md
│   │   └── ...
│   └── visualstraingauge/        # DIC 系统类
│       ├── index.md
│       └── DIC_Tracker_ONS-B-10/
│           ├── v0.5.1/           # 版本
│           │   ├── index.md
│           │   └── ...
│           └── v0.5.0/
│               ├── index.md
│               └── ...
├── ...
└── doc_maintain/                 # 文档维护（当前目录）
    ├── index.md                  # 文档维护首页（章节描述）
    ├── env_init.md
    ├── doc_write.md              # 文档的编写（当前页面）
    └── doc_format.md

须知

• src/SUMMARY.md 文件为目录结构，请勿删除。
• 所有的文档名称、相对文件路径和层级关系必须在 src/SUMMARY.md 文件中定义，否则无法在在线文档中显示。
  • 名称保持与文章大标题一致。
  • 层级关系和目录层级保持一致。
• 为防止自动化脚本解析出错，所有目录（文件夹）名称仅能由英文字母、下划线、减号、点和数字组成，且不能以下划线、减号、点或数字开头。

文档的格式

本在线文档使用 mdBook 构建，可在 mdBook 文档 - 格式查看详细信息。