使用 GitLab 和 Mkdocs 实现文档自动化

编写文档可能很麻烦，而且需要花费大量时间。在本文中，我将与大家分享我使用 DevOps 方法生成文档的方式。为了让工作更轻松，我们将探索自动化的艺术😃。

走吧各位😙

创建一个 GitLab 仓库

这很简单，请按照以下步骤操作：

• 登录你的 GitLab 账号
• 点击新建项目
• 给它起个名字：auto_docs
• 使用 README.md 文件进行初始化
• 公开或私密
• 点击创建

现在复制 URL 克隆项目，然后运行以下命令：
$ git clone https://gitlab.com/auto_docs.git

建立环境

我使用的是 Linux 环境，但同样的步骤也可以在 Windows 机器上实现。
为了能够按照我的步骤操作，你需要一些工具，这些工具必须安装在你的机器上……请确保已安装 Python 3，我使用的是 Python 3.8（最新版）。

创建虚拟环境

设置虚拟环境最简单的方法是通过执行 pip install virtualenv 来安装 virtualenv python 包。

导航至本地 GitLab 代码库并创建一个新的虚拟环境。

$ cd auto_docs/
$ virtualenv autodocs
$ source autodocs/bin/acivate

安装 Mkdocs 材料

请确保虚拟环境已激活。
使用以下命令安装 mkdocs 材料：`pip install mkdocs-material`。
此软件包需要一些依赖项才能运行……请使用requirement.txt文件安装它们，将依赖项列表复制粘贴到名为 `requirements.txt` 的文件中。

Babel==2.8.0
click==7.1.1
future==0.18.2
gitdb==4.0.4
GitPython==3.1.1
htmlmin==0.1.12
Jinja2==2.11.2
joblib==0.14.1
jsmin==2.2.2
livereload==2.6.1
lunr==0.5.6
Markdown==3.2.1
MarkupSafe==1.1.1
mkdocs==1.1
mkdocs-awesome-pages-plugin==2.2.1
mkdocs-git-revision-date-localized-plugin==0.5.0
mkdocs-material==5.1.1
mkdocs-material-extensions==1.0b1
mkdocs-minify-plugin==0.3.0
nltk==3.5
Pygments==2.6.1
pymdown-extensions==7.0
pytz==2019.3
PyYAML==5.3.1
regex==2020.4.4
six==1.14.0
smmap==3.0.2
tornado==6.0.4
tqdm==4.45.0

使用一条命令即可全部安装：pip install -r requirements.txt

现在是时候创建一个新的mkdocs项目了😅。

运行此命令：mkdocs new并验证您是否拥有以下结构：

|--auto_docs
    |--- docs
    |--- mkdocs.yml

• 该docs文件夹包含您的文档结构，其中包含子文件夹和 Markdown 文件。
• 该mkdocs.yml文件定义了所生成站点的配置。让我们运行以下命令来测试安装：`mkdocs serve`。站点将可以访问http://locahost:8000，您应该可以看到文档的初始界面。

设置 CI/CD

让我们启用 CI/CD 来自动化文档的构建和部署。请注意，GitLab 提供了一个名为 GitLab Pages 的功能，可以免费提供静态资源（HTML、JS、CSS）。仓库路径会被转换为指向您文档的 URL。

创建 CI/CD 文件

GitLab 使用 YAML 文件来保存流水线配置。CI
文件内容如下：

stages :
  - build
pages:
  stage: build
  image:
  name: squidfunk/mkdocs-material
  entrypoint:
    - ""
  script:
    - mkdocs build
    - mv site public
  artifacts:
    paths:
      - public
  only:
    - master
  tags:
    - gitlab-org-docker

这条流水线使用了一个 Docker 执行器，其镜像已预装了 mkdocs……mkdocs 会构建项目并将构建资源放在名为 site 的文件夹中……要使用 GitLab Pages，您需要将作业命名为 pages，并将 site 资源放入一个名为 public 的新文件夹中。
关于标签：请在“设置”→“CI/CD”→“运行器”下查看运行器部分，并选择一个带有 GitLab-org-docker 标签的共享运行器。
一切就绪！🎉 🎉 😸

哦！还有一件事……我们忘了虚拟环境文件……它们很大，而且在流水线中不需要……它们仅用于本地开发。流水线中的 mkdocs 镜像已经包含了必要的软件包。
所以……创建一个名为 .gitignore 的新文件，并添加以下几行：

auto_docs/ 
requirements.txt

auto_docs 文件夹与虚拟环境同名……别忘了😠！否则你会被惩罚，被扣 100Mi 的钱😝，而且你会一辈子都等不到完成这个过程哈哈😢。

现在运行git add . && git commit -m "initial commit" a && git push……前往您的 GitLab 代码库，点击 CI/CD → 流水线，点击蓝色图标并查看日志……任务成功后，导航至设置 -> 页面，然后点击您的新文档站点的链接（您需要等待约 10 分钟才能访问）。

最后，希望这篇文章对你有帮助！感谢阅读😺 😍！