feat: Auto publish docs to version "develop" (#269)

Auto publish docs to version "develop".

Every time we merge a change to main, we will publish a new version of document on "develop" version. (Instead of 1.1.0, 1.2.0, etc. which are published only when we release.). All of our docs are kept in the branch "gh-pages". The branch is special as it doesn't contain any source code, only published docs.

In the workflow, we publish the docs using two tools: mkdocs and mike. mkdocs generates a static website from ./doc into./site folder.

mike runs on the top of mkdocs to generate a new version into another directory. The idea of mike is that we keep the older version of doc published and never touch it. When we release a version 1.2.0, mike will create a new folder named 1.2.0 and put the new version of mkdocs generated site there. All of these happens in the "gh-pages" branch.

In this workflow, when we push to main branch, we will regenerate the special version "develop". This will replace the folder "develop" with the latest generated doc. (We also have the alias "latest" for the latest release version. This will be covered in the release workflow).

Author: ijemmy

.github/workflows/on-docs-change.yml

@@ -0,0 +1,44 @@
+name: Auto publish docs to version "develop"
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - 'CHANGELOG.md'
+      - 'mkdocs.yml'
+      - '.github/workflows/on-docs-change.yml'
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          fetch-depth: 0
+      - name: Set up Python
+        uses: actions/[email protected]
+        with:
+          python-version: "3.8"
+      - name: Install dependencies
+        run: |
+          pip install --upgrade pip 
+          pip install mike==1.1.2 mkdocs-material==8.0.5 mkdocs-git-revision-date-plugin==0.3.1
+      - name: Setup doc deploy
+        run: |
+          git config --global user.name Docs deploy
+          git config --global user.email [email protected]
+      - name: Build docs website and (TODO) API reference 
+        run: |
+          VERSION="develop"
+          ALIAS="stage"
+          mkdocs build
+          mike deploy --push --update-aliases "$VERSION" "$ALIAS"
+      - name: Deploy all docs
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./site
+          keep_files: true
+          destination_dir: develop/api 

.gitignore

@@ -32,4 +32,7 @@ coverage
 .vscode
 
 # Python virtual environments (for running mkdocs locally)
-venv
+venv
+
+# Static documentation site generated by Mkdocs
+site