# 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`网络
4. 确保可以访问公共盘

### 环境部署
1. <a href = "http://mkb.local/_static/deploy/deploy.zip"> 点我下载环境 </a>
2. 解压压缩文件后运行`deploy.bat`，并根据提示输入必要信息(仅限英文字符)
3. 若批处理正确运行完成，则应在解压目录下生成RUNME.bat
4. 双击RUNME.bat，应打开`vscode`环境并自动打开仓库目录
5. 现在您可以对仓库进行`签出`、`提交`等操作
6. 可能在提交时会提示输入用户名/密码(请输入gitea账户密码)

### VSCode-Git 使用说明

1. 在完成环境部署后，vscode中源代码管理功能应可用，从侧边栏中访问该功能
   ![VSCode Git](./Readme/img/vscode_git.png)
2. 想要对知识库页面进行编辑时，需**签出新分支**，参考下图步骤

    ![](./Readme/img/vscode_checkout.png)
    ![](./Readme/img/vscode_new_branch.png)

> [!CAUTION]
> 请不要直接对`master`分支进行修改！
>修改前请**签出**分支，修改完成后请发起***合并分支***请求

3. 在进行编辑后点击这里进行推送/发布新分支
   ![](./Readme/img/vscode_push.png)

> [!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)，推荐通过网页进行这一操作，其位置如下图：
   ![PR](./Readme/img/PR.png)

    > [!WARNING]  
    > 您仅应对您编辑的分支发起合并请求

2. 在创建合并请求界面，需清晰明了的创建标题及合并请求正文，同时在评审人一栏加入管理员进行审核，如需合作，也可在指派成员一栏邀请成员进行合作

    ![PR_Create](./Readme/img/PR_Create.png)