OceanBase Developer Handbook, Part 4: How to Modify OceanBase Documentation

Abstract

The OceanBase Developer Handbook mainly guides developers on how to get involved in OceanBase development, smoothing out the problems encountered during the preparatory work of contributing to OceanBase. This chapter currently consists of roughly the following articles, and more may be added in the future. For now, the OceanBase source code refers to the OceanBase Open Source Database Source Code Walkthrough series on the OceanBase open-source official site:

1. How to compile the OceanBase source code
2. How to set up the IDE development environment
3. How to become an OceanBase Contributor
4. How to modify OceanBase documentation
5. How to debug OceanBase
6. How to run tests
7. How to fix bugs

The process of modifying documentation in OceanBase is exactly the same as the process of modifying code. You can refer to “How to Become an OceanBase Contributor” and modify the documentation directly. If you don’t need to preview the documentation changes — for example, fixing a few typos directly — you can just edit it. But if you’re adding large blocks of text or new articles, it’s recommended to preview first. In that case, you’ll want to see how the changes look. You can install MkDocs to preview the result.

Steps

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.