文档

本文档主要讲解如何贡献项目文档到仓库中

准备工作¶

首先将项目源码Fork为自己的仓库
使用以下命令克隆项目源代码到本地

git clone https://github.com/<UserName>/dbm

UserName: 是指当前Fork项目的GitHub用户名, 比如我的是 qianmoQ,那么路径为github.com/qianmoQ/dbm

安装依赖¶

安装mkdocs工具

pip install mkdocs

注意

部分设备可能需要安装Python以及pip相关软件!

cd docs/

pip install -r requirements.txt

本地调试¶

Info

文档模块本地调试相对来说比较简单完成了安装依赖部分,使用以下命令启动本地服务

mkdocs serve

运行命令后会返回类似以下内容:

INFO     -  Building documentation...
INFO     -  The 'extra.alternate' configuration contains a 'link' option that should starts with './' in {'name': 'English', 'link': '/en/', 'lang': 'en'}
INFO     -  The 'extra.alternate' configuration contains a 'link' option that should starts with './' in {'name': 'Chinese (Simplified)', 'link': '/zh/',
            'lang': 'zh'}
WARNING  -  Language 'zh' is not supported by lunr.js, not setting it in the 'plugins.search.lang' option
INFO     -  Cleaning site directory
INFO     -  Translated navigation to en
INFO     -  Translated navigation to zh
INFO     -  Building en documentation
INFO     -  Building zh documentation
INFO     -  Documentation built in 1.71 seconds
INFO     -  [14:17:46] Serving on http://127.0.0.1:8000/

这标记着服务启动成功浏览器打开http://127.0.0.1:8000/即可看到已经发布的本地站点

贡献内容¶

Tip

我们建议您克隆下来的代码基于master重新构建一个分支用于代码的提交
构建新分支命令git checkout -b <BranchName>

assets: 资源文件(图片,文件等)

development: 开发相关文档

reference: 软件使用相关文档

release: 版本发布相关文档

修改mkdocs.yml配置文件,在nav条目下添加配置

Tip

比如贡献一个测试相关的文档,默认文件名为test.md,文件路径为docs/

修改后的配置如下

nav:
  ...
  - Test: docs/test.md

国际化名称配置(我们使用中文举例来说),在nav_translations条目下添加配置

nav_translations:
  zh: # 这里标记的是相关文档的国际化配置
    Test: Test

国际化文档

Note

国际化文档只需要将原有文件中添加国际化的简称即可,比如我们默认的是test.md,那中文的国际化文件为test.zh.md

代码提交¶

文档编写完成后我们使用git push命令将书写后的文件提交到个人仓库中,然后提交一个Pull requests到远程仓库的develop分支等待管理员审核合并后将会自动发布到官方站点

文档