编写须知¶

文档目录结构¶

文档采用分层目录结构组织，每个主要功能模块对应一个目录：

docs/zh/
├── index.md                          # 首页
├── quick_start/                      # 快速开始
│   └── index.md
├── account/                          # 用户账号管理
│   ├── accountapplication/
│   │   └── README.md
│   └── password/
│       └── README.md
├── connect/                          # 登录集群
│   ├── SSH_connection/
│   │   └── README.md
│   └── InteractiveConnection/
│       └── README.md
└── ...                              # 其他目录

文件创建规则

新增章节：在对应目录下新建 .md文件中文文档：使用 README.md或描述性文件名（如 ssh-configuration.md）英文文档：在相同目录下创建对应的 .en.md文件（如 README.en.md）

导航栏配置

导航结构在 mkdocs.yml文件的 nav部分配置：

nav:
    - 1. 简介: index.md
    - 2. 快速开始: quick_start/index.md
    - 3. 用户账号管理:
    - 3.1 账号申请: account/accountapplication/README.md
    - 3.2 密码管理: account/password/README.md
    #... 其他导航项

导航配置提示

新增文档后需要在 mkdocs.yml中添加对应的导航项

导航标题支持中文，便于用户理解

层级结构最多支持3级，保持导航简洁

文档编写流程¶

编写环境配置

Markdown 编辑器¶

下面列出了一些各平台上比较常用的 Markdown 编辑器。

全平台¶

VS Code: 微软开发的开源编辑器，安装 markdown 插件使用
Typora: Windows 平台上非常好用的编辑器
Sublime Text: 商业软件，可免费试用
Atom: Github 出品的编辑器，功能强大
Yu Writer: 漂亮好用的 Markdown 写作工具
Inkdrop: 商业软件，支持丰富插件
作业部落: 作业部落出的客户端
Laverna：支持 Dropbox 同步, 具有加密功能

Windows¶

MarkdownPad: 全功能编辑器，非常好用的 Markdown 编辑器
Remarkable

Linux¶

macOS¶

Ulysses：收费软件，支持 macOS, iPhone, iPad
MWeb：收费软件
Bear：收费软件
Mou: 现已收费
MacDown：开源免费
Paper：有内购功能，免费版支持 markdown

macOS 下的很多是收费软件。

git 使用环境¶

Windows¶

Git for Windows
WSL for Windows 10
cmder - 完整版
Github Desktop

ssh 环境配置¶

在 ~/.ssh/config 中设置文档服务器的别名，这一步很重要，没有这个文件则创建一个。

Host code
    Hostname code.ihep.ac.cn
    User git
    Port 22
    Identityfile ~/.ssh/id_rsa

此处的 ~/.ssh/id_rsa 为 个人的密钥，并且个人公钥 ~/.ssh/id_rsa.pub 已经添加到 Code 平台的个人 SSH Keys (点击) 中，注意 ~/.ssh/config 权限要设为 600, ~/.ssh/id_rsa 设置为 400。

git 配置文件¶

git 在配置文件为 ~/.gitconfig，没有这个文件则可以创建一个，可以在里面加入一些 alias，重要的是 name 和 email 这两项，将这两个变量改成自己的，没有这两项极可能会报错。不设置 git alias 也没问题。

[user]
    name = Bob
    email = bob@mail

[alias]
    a = add .
    br = branch
    ci = commit -m
    co = checkout
    df = diff
    dump = cat-file -p
    last = log -1 HEAD
    pl = pull
    ps = push
    st = status
    type = cat-file -t

内容编写步骤

标准工作流

拉取最新代码：git pull origin main

创建功能分支：git checkout -b feature/add-new-chapter

编写文档内容：在对应目录创建或编辑 .md文件

更新导航配置：在 mkdocs.yml中添加导航项（如需要）

提交更改：git add . && git commit -m "描述变更内容"

推送分支：git push origin feature/add-new-chapter

创建Pull Request：在Git仓库界面创建PR请求合并

多语言支持

对于需要中英文双语的内容，采用并行文件结构：

shell/
├── configuration/
│   ├── README.md          # 中文文档
│   └── README.en.md       # 英文文档
└── software/
    ├── README.md          # 中文文档  
    └── README.en.md       # 英文文档

自动化部署

自动化部署已配置

仓库位置：https://github.com/xxxxxx/user-manual

部署分支：main

触发条件：Pull Request合并到main分支后自动触发

部署地址：https://storage-docs.com/test/

查看部署结果

PR合并后约2-5分钟，即可在部署地址查看变更效果。如部署失败，会通过邮件通知相关人员。

内容维护指南¶

已有内容更新

对于已迁移的老版本内容：在对应目录下直接编辑现有的 .md文件保持文件路径不变，避免链接失效更新后记得同步修改对应的英文文档
新增内容创建

对于全新的功能文档：
```
# 1. 创建文档目录和文件
mkdir -p docs/新功能模块/子模块
touch docs/新功能模块/子模块/README.md

# 2. 编写内容后，更新导航配置
# 编辑 mkdocs.yml，在nav部分添加新项
```
3. 内容质量检查

在提交前请检查： - 文档结构清晰，标题层级正确
- 所有链接地址有效
- 代码示例可正常运行
- 图片资源已上传并引用正确
- 中英文文档内容同步更新`

文档引用¶

内部章节引用

使用相对路径进行章节间引用：

交叉引用

关于SSH连接的详细说明，请参考第四章登录集群作业提交的具体操作见第七章作业提交

外部资源引用

规范外部链接的引用格式：

## 参考资源
- [HTCondor官方文档](https://htcondor.org/documentation/){:target="_blank"}
- [Slurm快速指南](https://slurm.schedmd.com/quickstart.html){:target="_blank"}

图片资源引用

图片统一存放在对应文档一级目录下：
```
![INK申请应用](./ink/fig/application.png)
*图：申请INK应用*
```
图：申请INK应用
代码文件引用

如果引用外部代码文件：
```
示例配置文件：`configs/example.conf`
```

表格使用规范

表格应包含表头和对齐方式：

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `-J` | 字符串 | 无 | 作业名称 |
| `-N` | 整数 | 1 | 节点数量 |
| `-t` | 时间 | 01:00:00 | 运行时间 |

平台新功能¶

1. 标注功能¶

实现效果

Note

标注功能

实现方法在markdown中编辑文本格式为

!!! note
    重要但非关键的信息提示

支持类型

Note

Note

!!! note
    重要但非关键的信息提示

Abstract

Abstract

!!! abstract 标注内容
Info
Info
```
    !!! info
        标注内容
```

Tip

    !!! tip
        提高效率的小技巧

Success
Success
```
    !!! success
        标注内容
```
Question
Question
```
    !!! question
        标注内容
```

Warning

    !!! warning
        可能导致问题的操作提醒

Failure
Failure
```
    !!! failure
        标注内容
```

Danger

    !!! danger
        会导致数据丢失或系统故障的操作

2. 代码块¶

基础代码展示

支持多种代码语言，如：python、shell等，直接在```后指定语言即可，如：

    ```bash
    echo "Hello World!"
    ```

    echo "Hello World!"

    ```py
    def main():
    print("hello world!")
    return
    ```

   def main():
    print("hello world!")
    return

代码折叠

    === "Linux"

        ```bash
        ssh -l [用户名]@lxlogin.ihep.ac.cn #直接在命令行输入该命令，并输入密码

        ```

    === "Mac"
        ```bash
        ssh -l [用户名]@lxlogin.ihep.ac.cn #用法与linux相同
        ```

    === "Windows"
        ```bash
        #在SSH客户端输入以下命令
        ssh -l [用户名]@lxlogin.ihep.ac.cn
        ```

效果如下：

LinuxMacWindows

ssh -l [用户名]@lxlogin.ihep.ac.cn #直接在命令行输入该命令，并输入密码

ssh -l [用户名]@lxlogin.ihep.ac.cn #用法与linux相同

#在SSH客户端输入以下命令
ssh -l [用户名]@lxlogin.ihep.ac.cn

🤖 AI 助手