关于数据库:Nebula-Graph｜如何打造多版本文档中心

本文首发于 Nebula Graph Community 公众号

世界上没有完满的产品，每个不完满的产品都须要一份文档。

为什么须要文档

打造出一款产品后，咱们须要一份文档来答复以下问题：

• 设计这款产品的起因是什么（Why）
• 这是一款什么样的产品（What）
• 产品面向的用户是谁（Who）
• 在哪些场景下能够用这款产品（Where&When）
• 怎么应用（How）
• 产品的应用限度与其它须要留神的问题（Notes and limitations）
• ……

通过文档介绍这些信息，新读者能力更直观地理解产品，决定是否要用它，而产品的用户则能更顺利地应用它。

Nebula Graph 也是这样一款不完满的产品。因而咱们须要文档，更须要一个文档核心来集中保留并有序排列文档，供读者浏览和查找。

文档的需要

在最开始的时候，咱们的第一位文档工程师 @Amber 只有一个需要，那就是搭建一个英文文档网站。然而很快她就发现这可不仅仅是一个需要。

通过初步剖析，咱们至多须要做以下事件：

• 确定用什么写文档
• 找个中央寄存文档文件
• 让读者能够不便地浏览文档

随着工夫的推移和进一步思考，可达鸭发现了更多需要：

• P0：

  • 有中英文文档网站
  • 文档变更后主动公布

• P1：

  • 文档版本拆散
  • 内容搜寻

• P2：

  • 断链查看
  • 生成 PDF

• P3：

  • 复用
  • 暗藏
• 等等……

于是，可达鸭开始了打造文档核心的摸索之路。

打造文档核心

上面来解说下 Nebula 内容与文档团队是如何应用 MkDocs 和 GitHub 搭建文档核心的。在浏览本文的同时，能够从 Nebula Graph 文档核心（链接：https://docs.nebula-graph.com.cn/3.0.1/）和 GitHub 库（链接：https://github.com/vesoft-inc/nebula-docs-cn）查看相应的代码和成果示例。

MkDocs

MkDocs 是一个疾速、简略、好看的开源动态网站生成器，用于构建我的项目文档。文档源文件为 Markdown 格局，配置写在 YAML 文件中。

Mkdocs 反对：

• 多主题，每种主题有不同的性能。
• 自定义性能。
• 预览网站。

Material for MkDocs

Material for MkDocs 是最风行的 MkDocs 主题之一，反对通过 Python、Docker、Git 等形式装置。Nebula Graph 文档核心有若干性能由该主题提供。

Material for MkDocs 的装置和根底应用形式参考 Material 官网文档。

阐明：无需独自装置 MkDocs，Material 会将其一起装置。

部署文档核心

咱们应用 GitHub Pages 和 GitHub Actions 将 GitHub 文档库部署到文档核心，并实现批改文档后页面自动更新。

GitHub Pages 默认应用的域名为 {<user> | <organization>}.github.io，咱们应用了自定义域名。

设置基本功能

设置网站根本信息

设置根本信息须要应用的 mkdocs.yml 配置如下：

# 网站名称
site_name: Nebula Graph Database 手册
# 网站形容
site_description: Documentation for Nebula Graph Database
# 作者信息
site_author: Nebula Graph
# 网站（文档核心）的链接
site_url: https://docs.nebula-graph.com.cn/master/
# 版权信息
copyright: Copyright © 2021 Nebula Graph - 浙 ICP 备 20010487 号 

设置 GitHub 信息

Nebula 文档库托管在 GitHub 上，因而须要在 mkdocs.yml 中设置 GitHub 相干信息。

# GitHub 库的名称
repo_name: 'vesoft-inc/nebula-docs-cn'
# GitHub 库的链接
repo_url: 'https://github.com/vesoft-inc/nebula-docs-cn'
# 增加正确的门路后文档右上角会呈现编辑按钮，点击可间接跳转到编辑文件的页面
edit_uri: 'edit/master/docs-2.0/'
# 指定蕴含文档源 Markdown 文件的目录
docs_dir: docs-2.0
edit_uri 参数设置胜利后，每篇文档的如下地位会呈现编辑按钮，用于批改单篇文档十分不便。

设置导航栏

Markdown 文件在导航栏的显示程序能够通过 mkdocs.yml 文件中的 nav 字段配置。格局示例如下：

nav:
  - 前言: README.md
  - 简介:
      - 什么是 Nebula Graph: 1.introduction/1.what-is-nebula-graph.md
      - 数据模型: 1.introduction/2.data-model.md
      - ...
      - 服务架构:
        - 架构总览: 1.introduction/3.nebula-graph-architecture/1.architecture-overview.md
        - ...
 
  - 疾速入门:
      - 疾速入门流程: 2.quick-start/1.quick-start-workflow.md
      - 步骤 1：装置 Nebula Graph: 2.quick-start/2.install-nebula-graph.md
      - ...

显示成果如下：

丰盛文档核心性能

刚刚部署的文档核心仅有相似下图的默认的页面款式，咱们须要筛选配置项和插件实现更多功能。

利用 Material 主题

在 mkdocs.yml 文件中退出以下配置：

theme:
  name: material

并在 requirements.txt 文件中退出一行，内容为 mkdocs-material。这样就利用了 Material 主题的根本款式：

设置站点语言

Material for MkDocs 反对多种语言。例如，如果是中文文档，做如下设置：

theme:
  language: 'zh'

更改页面色彩

Material for MkDocs 提供了两类色彩主题，浅色背景的 default 和深色背景的 slate。编辑 mkdocs.yml 文件，退出 palette 字段：

theme:
  name: material
  palette:
    scheme: default

切换页面主题

咱们能够在深色和浅色主题之间切换，实现日间模式和夜间模式的成果。编辑 mkdocs.yml 文件，批改 palette 字段：

palette:
    - scheme: default
      primary: cyan
      accent: cyan
      toggle:
        icon: material/toggle-switch-off-outline
        name: Switch to dark mode
    - scheme: slate
      primary: deep orange
      accent: deep orange
      toggle:
        icon: material/toggle-switch
        name: Switch to light mode

除此以外，还能够自定义色彩。

自定义 logo

能够应用文档库内的各类型图片，包含但不限于 PNG、SVG 格局，或者内部网络上的图片，作为页面 logo。这样编辑 mkdocs.yml 文件：

theme:
  logo: assets/logo.png

如果是外链，间接在 logo: 前面设置链接即可。

对于搜寻

Material for MkDocs 内置了页面搜寻性能，这样编辑 mkdocs.yml 文件即可应用：

plugins:
  - search

然而，该搜寻性能对中文和英文混合的场景的反对有很多问题，咱们也还在寻找计划。

设置社交主页链接

Nebula Graph 是在 GitHub 开源的产品，因而文档核心设置了 GitHub 主页的 logo 和链接，形式如下：

  social:
    - icon: 'fontawesome/brands/github'
      link: 'https://github.com/vesoft-inc/nebula-docs-cn'

设置题目行自动隐藏

为了不让题目行遮挡内容，优化浏览体验，咱们设置了让题目行在页面下滑后自动隐藏。

theme:
  features:
    - header.autohide

版本拆散

版本拆散是 Nebula 文档核心的要害性能之一。开源开发的 Nebula Graph 迭代快，每个版本的个性都有区别，因而文档也依据产品性能分为不同版本。

版本治理

咱们应用 mike 做版本治理。

mike 的应用形式如下：

1. 在 requirements.txt 文件中退出一行，内容为：mike
2. 在 mkdocs.yml 中设置：

  version:
    method: mike

3. 在 /.github/workflows/deploy.yaml 中设置：

jobs:
  deploy:
    steps:
      - name: Mike Deploy master
        run: |
# 指定要部署的版本
          mike deploy 2.5.1 -p --rebase
# 指定文档核心默认跳转的版本，同时在历史版本中删除这句话。mike set-default 2.5.1 -p --rebase

版本公布

Nebula Graph 文档的版本与内核版本保持一致，公布文档新版本的形式如下：

1. 在 master 分支实现新版本文档开发，将相干 PR 合并。

2. 创立新的 GitHub 分支。

   1. 在文档的 GitHub 主页，点击分支切换按钮。
   2. 在 Find or create a branch... 文本框中输出新版本的名称，例如 v2.6.0。
   3. 点击下拉列表底部（倒数第二行）的 Create brach: xxx from master。

3. 批改配置文件。

   1. 批改新分支中的 /.github/workflows/deploy.yaml 文件，需批改的字段参考示例 commit。
   2. 批改新分支中的 /mkdocs.yml 文件，需批改的字段参考示例 commit。其中 palette 局部为主题色彩，具体阐明参考本文 ##更改页面色彩## 局部。
   3. 批改上个版本对应分支中的 /.github/workflows/deploy.yaml 文件，将 run 字段下的 mike set-default x.x.x -p --rebase 行删除，以勾销老版本的重定向。详情参考示例 commit。
4. 删除新分支的 overrides/partials/header.html 文件，勾销顶部告诉栏文件。该文件会影响 PDF 的生成，因而仅在 master 版本保留，用于告知读者 master 版本是开发版本，并指向最新的公布版本。
5. 在 GitHub [Actions] 页面查看最初一个 Action，查看 Mike Deploy xxx 部署，如有断链等报错即时解决。将非断链但临时不适宜公布的文件设置在 /mkdocs.yml 中的 exclude 字段，这样能起到暗藏成果，具体阐明参考正文。
6. 批改前一个版本的前言，倡议用户降级新版本。参考示例。

版本号主动变更

文档中的版本号有时须要依据版本批改，应用 macros 插件设置宏变量后，只有批改了 mkdocs.yml 文件中的设置，就能够不便地实现文档中的版本号主动变更。macros 的设置步骤如下：

1. 在 requirements.txt 文件中退出一行，内容为：mkdocs-macros-plugin

2. 在 mkdocs.yml 中的 extra 字段设置版本号的 macros 键值对，示例如下：

extra:
  nebula:
    release: 2.6.2

设置后，在 Markdown 代码中应用 {{<key>.<value>}} 的模式即可生成相应的版本号。进行了上述设置后，{{nebula.release}} 即代表 2.6.1。

源码和显示成果的比照如下：

这其实也是短语级别的内容复用。

以上，为 Nebula 内容与文档团队文档搭建实际。

当然咱们还有一些内容并未在本文展现，上面内容将在前面的文章中娓娓道来：

• mkdocs_latest_release_plugin
• mkdocs-git-revision-date-localized-plugin
• note
• mdx_truly_sane_lists
• pymdownx.superfences
• pymdownx.snippets
• pymdownx.arithmatex
• exclude
• mkdocs-with-pdf
• pydown-snippets
• Action 谬误排查
• 对于中文的非凡解决 https://github.com/vesoft-inc/nebula-docs-cn/blob/master/pkglist.txt

交换图数据库技术？退出 Nebula 交换群请先填写下你的 Nebula 名片，Nebula 小助手会拉你进群~~