Nebula Graph|如何打造多版本文档中心
世界上没有完美的产品,每个不完美的产品都需要一份文档。
为什么需要文档
打造出一款产品后,我们需要一份文档来回答以下问题:
- 设计这款产品的原因是什么(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 的使用方式如下:
在 requirements.txt 文件中加入一行,内容为:mike
在
mkdocs.yml
中设置:
version:
method: mike
- 在
/.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 文档的版本与内核版本保持一致,发布文档新版本的方式如下:
- 在 master 分支完成新版本文档开发,将相关 PR 合并。
- 创建新的 GitHub 分支。
- 在文档的 GitHub 主页,点击分支切换按钮。
- 在
Find or create a branch...
文本框中输入新版本的名称,例如 v2.6.0。 - 点击下拉列表底部(倒数第二行)的 Create brach: xxx from master 。
- 修改配置文件。
- 删除新分支的
overrides/partials/header.html
文件,取消顶部通知栏文件。该文件会影响 PDF 的生成,因此仅在 master 版本保留,用于告知读者 master 版本是开发版本,并指向最新的发布版本。 - 在 GitHub [Actions] 页面查看最后一个 Action,检查 Mike Deploy xxx 部署,如有断链等报错即时解决。将非断链但暂时不适合发布的文件设置在 /mkdocs.yml 中的 exclude 字段,这样能起到隐藏效果,详细说明参考注释。
- 修改前一个版本的前言,建议用户升级新版本。参考示例。
版本号自动变更
文档中的版本号有时需要根据版本修改,使用 macros 插件设置宏变量后,只要修改了 mkdocs.yml 文件中的设置,就可以方便地实现文档中的版本号自动变更。macros 的设置步骤如下:
- 在
requirements.txt
文件中加入一行,内容为:mkdocs-macros-plugin
2.在 mkdocs.yml
中的 extra
字段设置版本号的 macros 键值对,示例如下:
extra:
nebula:
release: 2.6.2
设置后,在 Markdown 代码中使用 {{.}} 的形式即可生成相应的版本号。进行了上述设置后,{{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 小助手会拉你进群~~
Nebula Graph|如何打造多版本文档中心的更多相关文章
- 一起买beta版本文档报告汇总
一起买beta版本文档报告汇总 031402401鲍亮 031402402曹鑫杰 031402403常松 031402412林淋 031402418汪培侨 031402426许秋鑫 一.Beta版本冲 ...
- Django-官网查询部分翻译(1.11版本文档)-QuerySet-字段查找-06
目录 Making queries 进行查询 创建一个对象(一条数据记录) 保存修改的表对象 保存外键字段或多对多字段(ForeignKey or ManyToManyField fields) Re ...
- 本文介绍如何使用 Docker Swarm 来部署 Nebula Graph 集群,并部署客户端负载均衡和高可用
本文作者系:视野金服工程师 | 吴海胜 首发于 Nebula Graph 论坛:https://discuss.nebula-graph.com.cn/t/topic/1388 一.前言 本文介绍如何 ...
- Nebula Graph 技术总监陈恒:图数据库怎么和深度学习框架进行结合?
引子 Nebula Graph 的技术总监在 09.24 - 09.30 期间同开源中国·高手问答的小伙伴们以「图数据库的设计和实践」为切入点展开讨论,包括:「图数据库的存储设计」.「图数据库的计算设 ...
- 图数据库 Nebula Graph 的安装部署
Nebula Graph:一个开源的分布式图数据库.作为唯一能够存储万亿个带属性的节点和边的在线图数据库,Nebula Graph 不仅能够在高并发场景下满足毫秒级的低时延查询要求,还能够实现服务高可 ...
- 图数据库 Nebula Graph 在 Boss 直聘的应用
本文首发于 Nebula Graph 官方博客:https://nebula-graph.com.cn/posts/nebula-graph-risk-control-boss-zhipin/ 摘要: ...
- Neo4j 导入 Nebula Graph 的实践总结
摘要: 主要介绍如何通过官方 ETL 工具 Exchange 将业务线上数据从 Neo4j 直接导入到 Nebula Graph 以及在导入过程中遇到的问题和优化方法. 本文首发于 Nebula 论坛 ...
- Nebula Graph 在企查查的应用
本文首发于 Nebula Graph Community 公众号 背景 企查查是企查查科技有限公司旗下的一款企业信用查询工具,旨在为用户提供快速查询企业工商信息.法院判决信息.关联企业信息.法律诉讼. ...
- 全方位讲解 Nebula Graph 索引原理和使用
本文首发于 Nebula Graph Community 公众号 index not found?找不到索引?为什么我要创建 Nebula Graph 索引?什么时候要用到 Nebula Graph ...
- macOS 安装 Nebula Graph 看这篇就够了
本文首发于 Nebula Graph Community 公众号 背景 刚学习图数据的内容,当前网上充斥大量的安装文档,参差不齐,部署起来令人十分头疼. 现整理一份比较完整的安装文档,供大家学习参考, ...
随机推荐
- 一种轻量分表方案-MyBatis拦截器分表实践
背景 部门内有一些亿级别核心业务表增速非常快,增量日均100W,但线上业务只依赖近一周的数据.随着数据量的迅速增长,慢SQL频发,数据库性能下降,系统稳定性受到严重影响.本篇文章,将分享如何使用MyB ...
- es7如何使用await发送请求
handleLogin() { this.$http.post("login", this.formLabelAlign).then(res => { const { dat ...
- 【0基础学爬虫】爬虫基础之自动化工具 Pyppeteer 的使用
大数据时代,各行各业对数据采集的需求日益增多,网络爬虫的运用也更为广泛,越来越多的人开始学习网络爬虫这项技术,K哥爬虫此前已经推出不少爬虫进阶.逆向相关文章,为实现从易到难全方位覆盖,特设[0基础学爬 ...
- 阿里天池实验室简明教程以及Docker安装使用[一]
1.天池notebook简介和使用 天池实验室是基于PAI DSW探索版开发的,PAI DSW (Data Science Workshop)是为算法开发者量身打造的云天池实验室是基于PAI DSW探 ...
- 【1】VScode 中文界面方法-------超简单教程
相关文章: [一]tensorflow安装.常用python镜像源.tensorflow 深度学习强化学习教学 [二]tensorflow调试报错.tensorflow 深度学习强化学习教学 [三]t ...
- DevToys(开发工具) v1.0.2.1
从事开发工作的朋友们千万不要错过了!今天为大家带来的这款软件可以说是开发人员的必备工具,它就是DevToys软件!DevToys中包含了许多强大实用的开发工具,能够帮助用户将程序开发变得更加简单大大降 ...
- php获取服务器操作系统等信息
php获取服务器操作系统等信息 获取请求页面时通信协议的名称和版本: $_SERVER['SERVER_PROTOCOL'] 例如,"HTTP/1.0". PHP程式版本:< ...
- DoraCloud桌面模板制作教程
模板制作是桌面云部署时的一项重要工作.模板的质量直接影响到虚拟桌面业务运行的稳定性.安全性和用户体验.制作模板需要完成如下一些工作: 安装Windows桌面操作系统. 安装虚拟化平台相关的半虚拟化驱动 ...
- ABC 311 A - E
ABC 311 A - E 不提供代码 A 题意:求一个字符串的第一个 ABC 最早出现的位置,可以打乱顺序,可以间隔 建立三个变量,然后以此判断即可,直到三种字符都出现就可以了 B 题意:给定每个人 ...
- Delphi库单元结构
单元(unit)是组成Pascal 程序的单独的源代码模块,单元由函数和过程组成,这些函数和过程能被主程序调用. 一个标准的单元文件格式如下: unit Unit1: //单元头 interface ...