Nebula Graph｜How to create a multi-version documentation center

This article was first published on the Nebula Graph Community public account

There is no perfect product in the world, and every imperfect product needs a document.

Why do you need documentation

After building a product, we need a document to answer the following questions:

• What is the reason for designing this product (Why)
• What kind of product is this (What)
• Who is the product for?
• In which scenarios can this product be used (Where&When)
• How to use (How)
• Product usage limitations and other issues to be aware of (Notes and limitations)
• ...

By introducing this information through the documentation, new readers can understand the product more intuitively, decide whether to use it, and users of the product can use it more smoothly.

Nebula Graph is also such an imperfect product. Therefore, we need documents, and more importantly, a document center to centrally save and order documents for readers to read and find.

Documentation requirements

At the very beginning, our first documentation engineer @Amber had only one requirement, which was to build an English documentation website. However, she soon discovered that this was not just a need.

After preliminary analysis, we need to do at least the following things:

• Decide what to write the document with
• Find a place to store your document files
• Make it easy for readers to read the documentation

Over time and further thinking, Duck discovered more needs:

• P0:

  • Website with Chinese and English documentation
  • Automatically publish after document changes

• P1:

  • Document version separation
  • Content search

• P2:

  • Broken link check
  • Generate PDF

• P3:

  • multiplex
  • hide
• and many more……

As a result, Da Duck began to explore the way to build a document center.

Create a document center

Let's explain how the Nebula content and documentation team uses MkDocs and GitHub to build a documentation center. While reading this article, you can download it from the Nebula Graph Documentation Center (link: https://docs.nebula-graph.com.cn/3.0.1/ ) and the GitHub repository (link: https://github.com/vesoft- inc/nebula-docs-cn ) to see the corresponding code and effect examples.

MkDocs

MkDocs is a fast, simple, and beautiful open source static website generator for building project documentation. The documentation source file is in Markdown format, and the configuration is written in a YAML file.

Mkdocs supports:

• Multiple themes, each with different functions.
• custom function.
• Preview the website.

Material for MkDocs

Material for MkDocs is one of the most popular MkDocs themes and supports installation via Python, Docker, Git, and more. The Nebula Graph Documentation Center has several features provided by this theme.

For the installation and basic usage of Material for MkDocs, please refer to the official Material documentation .

Note: There is no need to install MkDocs separately, Material will install it together.

Deployment Documentation Center

We use GitHub Pages and GitHub Actions to deploy the GitHub document library to the document center, and realize the automatic page update after the document is modified.

The default domain name used by GitHub Pages is {<user> | <organization>}.github.io , we used a custom domain name .

Set up basic functions

Set basic website information

To set the basic information need to use mkdocs.yml configuration is as follows:

 # 网站名称
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号

Set up GitHub information

The Nebula documentation repository is hosted on GitHub, so GitHub related information needs to be set in mkdocs.yml .

 # 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 参数设置成功后，每篇文档的如下位置会出现编辑按钮，用于修改单篇文档非常方便。

Set up the navigation bar

The display order of Markdown files in the navigation bar can be configured through the mkdocs.yml nav field in the file ---7e8b907122276aa9304ab04d2bc6707a---. An example of the format is as follows:

 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
      - ...

The display effect is as follows:

Rich document center functions

The just-deployed document center only has a default page style like the one shown below. We need to select configuration items and plug-ins to achieve more functions.

Apply the Material theme

Add the following configuration to the mkdocs.yml file:

 theme:
  name: material

And add a line to the requirements.txt file, the content is mkdocs-material. This applies the basic styling of the Material theme:

Set site language

Material for MkDocs supports multiple languages. For example, if it is a Chinese document, do the following settings:

 theme:
  language: 'zh'

Change page color

Material for MkDocs provides two color themes, default for light backgrounds and slate for dark backgrounds. Edit mkdocs.yml file and add the palette field:

 theme:
  name: material
  palette:
    scheme: default

Switch page theme

We can switch between dark and light themes for day mode and night mode effects. Edit the mkdocs.yml file and modify the palette field:

 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

In addition, you can also customize the color .

custom logo

Various types of pictures in the document library can be used, including but not limited to PNG, SVG format, or pictures on external networks, as the page logo. Edit mkdocs.yml file like this:

 theme:
  logo: assets/logo.png

If it is an external link, you can set the link directly after logo: .

About Search

Material for MkDocs has a built-in page search function, so you can edit the mkdocs.yml file to use:

 plugins:
  - search

However, there are many problems with the support of this search function for mixed Chinese and English scenarios, and we are still looking for solutions.

Set up social page links

Nebula Graph is an open source product on GitHub, so the documentation center sets the logo and link of the GitHub homepage in the following ways:

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

Set the header row to auto-hide

In order not to let the title row block the content and optimize the reading experience, we have set the title row to be automatically hidden after the page slides down.

 theme:
  features:
    - header.autohide

Version separation

Version separation is one of the key features of the Nebula Documentation Center. The open source developed Nebula Graph iterates quickly, and the features of each version are different, so the documentation is also divided into different versions according to product functions.

Version management

We use mike for version management.

Mike is used as follows:

1. Add a line to the requirements.txt file that reads: mike
2. In mkdocs.yml set:

 version:
    method: mike

3. In /.github/workflows/deploy.yaml set:

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

Version release

The version of the Nebula Graph document is consistent with the kernel version. The way to release a new version of the document is as follows:

1. Complete the development of the new version of the document in the master branch, and merge the relevant PR.

2. Create a new GitHub branch.

   1. On the documentation's GitHub home page, click the branch toggle button.
   2. Enter the name of the new version in the Find or create a branch... text box, eg v2.6.0.
   3. Click Create brach: xxx from master at the bottom of the drop-down list (second-to-last row).

3. Modify the configuration file.

   1. Modify the /.github/workflows/deploy.yaml file in the new branch, refer to the example commit for the fields to be modified.
   2. Modify the /mkdocs.yml file in the new branch, refer to the example commit for the fields to be modified. The palette part is the theme color. For details, please refer to the ##Change page color## section of this article.
   3. Modify the /.github/workflows/deploy.yaml file in the corresponding branch of the previous version, and delete the mike set-default x.x.x -p --rebase line under the run field to cancel the redirection of the old version. Refer to the example commit for details.
4. Delete the overrides/partials/header.html file of the new branch and cancel the top notification bar file. This file affects the generation of the PDF and is therefore only kept in the master version to inform readers that the master version is a development version and points to the latest release version.
5. View the last Action on the GitHub [Actions] page, check the Mike Deploy xxx deployment, and resolve any errors such as broken links. Set the non-broken link but temporarily unsuitable for publishing in the exclude field in /mkdocs.yml, which can have a hidden effect, and refer to the comments for details.
6. Modify the preface of the previous version, and recommend users to upgrade to the new version. Reference example .

Version number changes automatically

The version number in the document sometimes needs to be modified according to the version. After using the macros plug-in to set macro variables, as long as the settings in the mkdocs.yml file are modified, the version number in the document can be automatically changed easily. The steps for setting macros are as follows:

1. Add a line to the requirements.txt file, the content is: mkdocs-macros-plugin

2. In the mkdocs.yml extra field in ---166b187383a9782716fa7619f9a57cf8---, set the macro key-value pair of the version number. The example is as follows:

 extra:
  nebula:
    release: 2.6.2

After setting, use the form of {{<key>.<value>}} in the Markdown code to generate the corresponding version number. With the above settings, {{nebula.release}} stands for 2.6.1.

The comparison between the source code and the display effect is as follows:

This is actually a phrase-level content reuse.

Above, build practice for the Nebula content and documentation team documentation.

Of course, we still have some content that has not been shown in this article. The following content will be explained in the following articles:

• 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 Troubleshooting
• About the special treatment of Chinese https://github.com/vesoft-inc/nebula-docs-cn/blob/master/pkglist.txt

Exchange graph database technology? To join the Nebula exchange group, please fill in your Nebula business card first, and the Nebula assistant will pull you into the group~~