modify mkdocs (#278)

* remove github workflow

* update mkdocs.yml and add mkdocs.md

* add site/ to .gitignore

* leave requirements.txt in docs/

* update mkdocs.md

.github/workflows/publish-docs.yaml

@@ -1,30 +0,0 @@
-name: Publish docs via GitHub Pages
-on:
-  push:
-    branches:
-      - master
-
-jobs:
-  deploy:
-    runs-on: ubuntu-18.04
-    steps:
-      - uses: actions/checkout@v2
-
-      - name: Setup Python
-        uses: actions/setup-python@v1
-        with:
-          python-version: '3.7'
-          architecture: 'x64'
-
-      - name: Install dependencies
-        run: |
-          pip install --upgrade pip
-          pip install -r docs/requirements.txt
-      - name: Build
-        run: mkdocs build -f docs/mkdocs.yml
-
-      - name: Deploy
-        uses: peaceiris/actions-gh-pages@v3
-        with:
-          github_token: ${{ secrets.PUBLISH_DOCS_TOKEN }}
-          publish_dir: site

.gitignore

@@ -86,6 +86,9 @@ test/tmp
 test/var
 *.ccls-cache/
 
+###### Docs website files
+site
+
 ###### Intellij files
 .idea
 cmake-build-debug

docs/README.md

@@ -1,20 +0,0 @@
-# OceanBase Documentation
-Welcome to the OceanBase documentation!
-
-This directory stores all the source files of OceanBase documentation website.
-
-## Starting a server locally
-
-OceanBase documentation website is built with [MkDocs](https://www.mkdocs.org/). To install all dependencies, run:
-
-    $ pip install -r ./requirements.txt
-
-Generate the site, and start a server locally:
-
-    $ mkdocs serve
-
-Open up http://127.0.0.1:8000/ in your browser, and you'll see the default home page.
-
-## Contributing
-
-See [How to Contribute](../CONTRIBUTING.md).

mkdocs.md

@@ -0,0 +1,45 @@
+# Build documentation with MkDocs
+
+OceanBase documentation is built with [MkDocs](https://www.mkdocs.org/). You can check [`mkdocs.yml`](mkdocs.yml) for more information.
+
+## 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:
+
+    $ pip install -r docs/requirements.txt
+
+## 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](https://www.mkdocs.org/user-guide/configuration/).
+
+**Note:** `docs/` is the default value of `docs_dir`, which means `docs/` is equivalent to `./` in `mkdocs.yml`.
+
+## Contribute
+
+See [How to contribute](CONTRIBUTING.md).

mkdocs.yml

@@ -2,8 +2,7 @@ site_name: OceanBase 手册
 repo_url: 'https://github.com/oceanbase/oceanbase'
 repo_name: 'OceanBase'
 edit_uri: 'edit/master/docs/'
-docs_dir: './'
+
-site_dir: '../site'
 theme:
   name: 'material'
 nav: