Skip to content

编写须知

文档目录结构

  1. 文档采用分层目录结构组织,每个主要功能模块对应一个目录:

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

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

  3. 导航栏配置

    导航结构在 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级,保持导航简洁

文档编写流程

  1. 编写环境配置

Markdown 编辑器

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

全平台

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

Windows

Linux

macOS

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

macOS 下的很多是收费软件。

git 使用环境

Windows

ssh 环境配置

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

Host codeHostname code.ihep.ac.cnUser gitPort 22Identityfile ~/.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=Bobemail=bob@mail[alias]a=add.br=branchci=commit-mco=checkoutdf=diffdump=cat-file-plast=log-1HEADpl=pullps=pushst=statustype=cat-file-t
  1. 内容编写步骤

    标准工作流

    拉取最新代码: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请求合并

  2. 多语言支持

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

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

  3. 自动化部署

    自动化部署已配置

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

    部署分支:main

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

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

    查看部署结果

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

内容维护指南

  1. 已有内容更新

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

  2. 新增内容创建

    对于全新的功能文档:

    # 1. 创建文档目录和文件mkdir -p docs/新功能模块/子模块touch docs/新功能模块/子模块/README.md# 2. 编写内容后,更新导航配置# 编辑 mkdocs.yml,在nav部分添加新项
    3. 内容质量检查

    在提交前请检查: - 文档结构清晰,标题层级正确

    • 所有链接地址有效

    • 代码示例可正常运行

    • 图片资源已上传并引用正确

    • 中英文文档内容同步更新`

文档引用

  1. 内部章节引用

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

    交叉引用

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

  2. 外部资源引用

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

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

  3. 图片资源引用

    图片统一存放在对应文档一级目录下:

    ![INK申请应用](./ink/fig/application.png)*图:申请INK应用*
    INK申请应用图:申请INK应用

  4. 代码文件引用

    如果引用外部代码文件:

    示例配置文件:`configs/example.conf`

  5. 表格使用规范

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

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

平台新功能

1. 标注功能

  • 实现效果

Note

标注功能

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

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

  • 支持类型

    • Note

    Note

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

      Abstract

      !!! abstract 标注内容

    • Info

      Info

      !!! info标注内容
    • Tip

      Tip

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

      Success

      !!! success标注内容
    • Question

      Question

      !!! question标注内容
    • Warning

      Warning

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

      Failure

      !!! failure标注内容
    • Danger

      Danger

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

2. 代码块

  • 基础代码展示

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

```bashecho"Hello World!"```
echo"Hello World!"
```pydefmain():print("hello world!")return```
defmain():print("hello world!")return
  • 代码折叠
=== "Linux"```bashssh -l [用户名]@lxlogin.ihep.ac.cn #直接在命令行输入该命令,并输入密码```=== "Mac"```bashssh -l [用户名]@lxlogin.ihep.ac.cn #用法与linux相同```=== "Windows"```bash#在SSH客户端输入以下命令ssh -l [用户名]@lxlogin.ihep.ac.cn```

效果如下:

ssh-l[用户名]@lxlogin.ihep.ac.cn#直接在命令行输入该命令,并输入密码
ssh-l[用户名]@lxlogin.ihep.ac.cn#用法与linux相同
#在SSH客户端输入以下命令ssh-l[用户名]@lxlogin.ihep.ac.cn
AI 助手
快速提问 ×

有问题?输入后跳转到对话页继续交流

Baidu
map