yuysh
3865ed0c94
Build Sphinx Documentation / Build Documentation from PR Branch (pull_request) Has been cancelled
97 lines
4.0 KiB
Markdown
97 lines
4.0 KiB
Markdown
# MKB
|
|
|
|
Manlink Knowledge Base
|
|
---
|
|
## About
|
|
此仓库用于储存及生成知识库网页
|
|
|
|
[点我访问正式版网页](http://mkb.local)
|
|
|
|
*[若无法访问，尝试直接访问ip](http://172.18.32.40/)*
|
|
|
|
---
|
|
## Getting Started
|
|
|
|
### 前期准备
|
|
1. 在[这里](http://mkb.local:3000/user/sign_up)注册账号
|
|
2. 通知管理员将账户加入`Manlink_Doc` 仓库
|
|
3. 确保连接`manlink_internal`网络
|
|
|
|
### 环境部署
|
|
1. <a href = "http://mkb.local/_static/deploy/deploy.exe"> 点我下载环境 </a>
|
|
2. 解压压缩文件后运行`deploy.bat`，并根据提示输入必要信息(仅限英文字符)
|
|
3. 若批处理正确运行完成，则应在解压目录下生成RUNME.bat
|
|
4. 双击RUNME.bat，应打开`vscode`环境并自动打开仓库目录
|
|
5. 现在您可以对仓库进行`签出`、`提交`等操作
|
|
6. 可能在提交时会提示输入用户名/密码(请输入gitea账户密码)
|
|
|
|
### VSCode-Git 使用说明
|
|
|
|
1. 在完成环境部署后，vscode中源代码管理功能应可用，从侧边栏中访问该功能
|
|
|
|
2. 想要对知识库页面进行编辑时，需**签出新分支**，参考下图步骤
|
|
|
|
|
|
|
|
|
|
> [!CAUTION]
|
|
> 请不要直接对`master`分支进行修改！
|
|
>修改前请**签出**分支，修改完成后请发起***合并分支***请求
|
|
|
|
3. 在进行编辑后点击这里进行推送/发布新分支
|
|
|
|
|
|
> [!NOTE]
|
|
>
|
|
> 想要更加详细了解Git可以参考[这篇文档](./Readme/git.md)
|
|
|
|
### 添加/修改内容
|
|
|
|
1. 本知识库采用`Sphinx`作为解析、生成工具，并*推荐*主要以`Markdown`语言作为文档的原始语言格式,`reStructuredText`语言作为辅助
|
|
2. `source`文件夹即为知识库原始文件夹，通过文件树及`index.rst`进行网页层级管理
|
|
|
|
> [!IMPORTANT]
|
|
> 请**不要**修改`source/conf.py`其为`Sphinx`配置文件！如需修改请提交PR至管理员
|
|
|
|
3. 创建文档时：
|
|
1. 请将图片放入`_images/`目录下，建议单独创建文件夹以保证目录整洁
|
|
2. 其他数据，如：实验数据、日志等，请放入`_static/`目录下，同样建议创建文件夹以保证目录整洁
|
|
3. 对于新创建的文档：
|
|
1. 如已存在对应目录，则仅需在对应目录下创建文档即可，建议保证文件名具有**通俗易懂**的可读性
|
|
2. 如不存在目录，则需创建目录及`index.rst`，并更新上级的`index.rst`或`index.md`，具体内容可参考已有文档，如[子目录index.rst](./source/Mars_1KS/DC/PPMU/1.0/index.rst)及[父目录index.rst](./source/Mars_1KS/index.rst)之后新建文档
|
|
|
|
> [!Note]
|
|
>
|
|
> 对于Markdown语法，可以参考[这篇文档](./Readme/markdown.md)
|
|
|
|
|
|
### 测试及合并请求
|
|
|
|
1. 在您完成编辑后可以对您的分支发起合并请求(Pull Request)，推荐通过网页进行这一操作，其位置如下图：
|
|
|
|
|
|
> [!WARNING]
|
|
> 您仅应对您编辑的分支发起合并请求
|
|
|
|
2. 在创建合并请求界面，需清晰明了的创建标题及合并请求正文，如需合作，也可在指派成员一栏邀请成员进行合作
|
|
|
|
|
|
|
|
3. 创建合并分支后会默认触发自动化部署，如下图所示
|
|
|
|
|
|
|
|
在正常情况下，自动化部署应顺利完成(理论运行时间<5min)，运行完成后可在[http://mkb.local:880](http://mkb.local:880)查看及调试网页
|
|
|
|
>[!NOTE]
|
|
>此时如有问题，仍可以通过commit进行提交，提交后会触发自动化部署
|
|
|
|
>[!WARNING]
|
|
>服务器性能有限，且已人为将自动化部署并发数设为1，请尽可能避免在Pr后提交Commit
|
|
|
|
4. 在检查完测试网页后可添加管理员作为评审人，之后须有管理员评审并在通过审核后将分支合并至主分支
|
|
|
|
|
|
|
|
|
|
5. 最后需管理员手动合并测试网页至正式版网页 |