| |
|
开发:
C++知识库
Java知识库
JavaScript
Python
PHP知识库
人工智能
区块链
大数据
移动开发
嵌入式
开发工具
数据结构与算法
开发测试
游戏开发
网络协议
系统运维
教程: HTML教程 CSS教程 JavaScript教程 Go语言教程 JQuery教程 VUE教程 VUE3教程 Bootstrap教程 SQL数据库教程 C语言教程 C++教程 Java教程 Python教程 Python3教程 C#教程 数码: 电脑 笔记本 显卡 显示器 固态硬盘 硬盘 耳机 手机 iphone vivo oppo 小米 华为 单反 装机 图拉丁 |
-> 开发工具 -> Nebula Graph|如何打造多版本文档中心 -> 正文阅读 |
|
[开发工具]Nebula Graph|如何打造多版本文档中心 |
作者:_GitHub__99 |
世界上没有完美的产品,每个不完美的产品都需要一份文档。 为什么需要文档打造出一款产品后,我们需要一份文档来回答以下问题:
通过文档介绍这些信息,新读者才能更直观地了解产品,决定是否要用它,而产品的用户则能更顺利地使用它。 Nebula Graph也是这样一款不完美的产品。因此我们需要文档,更需要一个文档中心来集中保存并有序排列文档,供读者阅读和查找。 文档的需求在最开始的时候,我们的第一位文档工程师@Amber只有一个需求,那就是搭建一个英文文档网站。然而很快她就发现这可不仅仅是一个需求。 经过初步分析,我们至少需要做以下事情:
随着时间的推移和进一步思考,可达鸭发现了更多需求:
于是,可达鸭开始了打造文档中心的探索之路。 打造文档中心下面来讲解下 Nebula 内容与文档团队是如何使用 MkDocs 和 GitHub 搭建文档中心的。在阅读本文的同时,可以从 Nebula Graph 文档中心(链接:https://docs.nebula-graph.com.cn/3.0.1/)和 GitHub 库(链接:https://github.com/vesoft-inc/nebula-docs-cn)查看相应的代码和效果示例。 MkDocsMkDocs 是一个快速、简单、美观的开源静态网站生成器,用于构建项目文档。文档源文件为 Markdown 格式,配置写在 YAML 文件中。 Mkdocs 支持:
Material for MkDocsMaterial for MkDocs 是最流行的 MkDocs 主题之一,支持通过 Python、Docker、Git 等方式安装。Nebula Graph 文档中心有若干功能由该主题提供。 Material for MkDocs 的安装和基础使用方式参考 Material 官方文档。
部署文档中心我们使用 GitHub Pages 和 GitHub Actions 将 GitHub 文档库部署到文档中心,并实现修改文档后页面自动更新。 GitHub Pages 默认使用的域名为 设置基本功能设置网站基本信息设置基本信息需要使用的
设置 GitHub 信息Nebula 文档库托管在 GitHub 上,因此需要在
设置导航栏Markdown 文件在导航栏的显示顺序可以通过
显示效果如下: 丰富文档中心功能刚刚部署的文档中心仅有类似下图的默认的页面样式,我们需要挑选配置项和插件实现更多功能。 应用 Material 主题在
并在 设置站点语言Material for MkDocs 支持多种语言。例如,如果是中文文档,做如下设置:
更改页面颜色Material for MkDocs 提供了两类颜色主题,浅色背景的 default 和深色背景的 slate。编辑
切换页面主题我们可以在深色和浅色主题之间切换,实现日间模式和夜间模式的效果。编辑 mkdocs.yml 文件,修改 palette 字段:
除此以外,还可以自定义颜色。 自定义 logo可以使用文档库内的各类型图片,包括但不限于 PNG、SVG 格式,或者外部网络上的图片,作为页面 logo。这样编辑
如果是外链,直接在 关于搜索Material for MkDocs 内置了页面搜索功能,这样编辑
但是,该搜索功能对中文和英文混合的场景的支持有很多问题,我们也还在寻找方案。 设置社交主页链接Nebula Graph 是在 GitHub 开源的产品,因此文档中心设置了 GitHub 主页的 logo 和链接,方式如下:
设置标题行自动隐藏为了不让标题行遮挡内容,优化阅读体验,我们设置了让标题行在页面下滑后自动隐藏。
版本分离版本分离是 Nebula 文档中心的关键功能之一。开源开发的 Nebula Graph 迭代快,每个版本的特性都有区别,因此文档也根据产品功能分为不同版本。 版本管理我们使用 mike 做版本管理。 mike 的使用方式如下:
版本发布Nebula Graph 文档的版本与内核版本保持一致,发布文档新版本的方式如下:
版本号自动变更文档中的版本号有时需要根据版本修改,使用 macros 插件设置宏变量后,只要修改了 mkdocs.yml 文件中的设置,就可以方便地实现文档中的版本号自动变更。macros 的设置步骤如下:
2.在
设置后,在 Markdown 代码中使用 {{.}} 的形式即可生成相应的版本号。进行了上述设置后,{{nebula.release}} 即代表 2.6.1。 源码和显示效果的对比如下: 这其实也是短语级别的内容复用。 以上,为 Nebula 内容与文档团队文档搭建实践。 当然我们还有一些内容并未在本文展示,下面内容将在后面的文章中娓娓道来:
交流图数据库技术?加入 Nebula 交流群请先填写下你的 Nebula 名片,Nebula 小助手会拉你进群~~ |
|
|
上一篇文章 下一篇文章 查看所有文章 |
|
开发:
C++知识库
Java知识库
JavaScript
Python
PHP知识库
人工智能
区块链
大数据
移动开发
嵌入式
开发工具
数据结构与算法
开发测试
游戏开发
网络协议
系统运维
教程: HTML教程 CSS教程 JavaScript教程 Go语言教程 JQuery教程 VUE教程 VUE3教程 Bootstrap教程 SQL数据库教程 C语言教程 C++教程 Java教程 Python教程 Python3教程 C#教程 数码: 电脑 笔记本 显卡 显示器 固态硬盘 硬盘 耳机 手机 iphone vivo oppo 小米 华为 单反 装机 图拉丁 |
360图书馆 购物 三丰科技 阅读网 日历 万年历 2024年11日历 | -2024/11/26 0:51:32- |
|
网站联系: qq:121756557 email:121756557@qq.com IT数码 |