《OceanBase开发者手册》之四 如何修改OceanBase文档

Abstract

《OceanBase开发者手册》 主要指导开发者如何参与到OceanBase 的研发, 铺平参与OceanBase 开发的准备工作遇到的问题, 当前章节大概这几篇文章, 未来可能会增加部分文章, 目前OceanBase 源码参考OceanBase 开源官网的《开源数据库OceanBase源码解读》 系列 :

1. 如何编译OceanBase源码
2. 如何设置IDE开发环境
3. 如何成为OceanBase Contributor
4. 如何修改OceanBase文档
5. 如何debug OceanBase
6. 如何运行测试
7. 如何修bug
   ​

在OceanBase 修改文档的过程, 和修改代码的过程完全一样, 可以参考《如何成为OceanBase Contributor》直接修改文档, 如果不做文档修改的预览, 比如直接修改少量的错别字, 可以直接修改, 但如果增加大段文字或新增文章, 建议做预览一下. 那在这种情况下, 需要看看, 修改的效果如何. 可以安装mkdocs, 对修改的效果进行预览.

​

步骤

Build documentation with MkDocs

OceanBase documentation is built with MkDocs. You can check mkdocs.yml for more information.
Please install MkDocs according to the installation documents of MkDocs

Requirements

Before installing dependencies, please make sure you have installed a recent version of Python 3 and pip.

Then you can run the following command in your terminal at current directory:

$ pip install -r requirements.txt
$ pip install mkdocs-material

Build the documentation

You can build the documentation by running the following command:

$ mkdocs build

This will create a new directory to store the output files, which is site/ by default.

Start a server locally

You can start a server locally by running the following command:

$ mkdocs serve

Open up http://127.0.0.1:8000/ in your browser, and you’ll see the default home page.

Modify pages

Edit a page

If you want to modify the content of a page, you can edit the markdown file in docs/ directory directly.

Modify the layout of pages

To modify the layout of pages, you need to edit mkdocs.yml.

For configuration details, see MkDocs User Guide.

Note the following rules when editing documents:

• All paths in nav must be relative to the docs_dir, which is docs by default. So here ./ is equivalent to docs.
• All internal links must be relative paths, as MkDocs only supports regular Markdown linking syntax.