docs: v15 documentation infrastructure

Besides the documentation itself, this commit also contains the necessary CI support on GitHub Actions. Currently, CI will only check the building of documentation, but will not deploy it to GitHub Pages.
ApsaraDB · Sep 5, 2024 · 25ed000 · 25ed000
1 parent a3ba87d
commit 25ed000
Show file tree

Hide file tree

Showing 350 changed files with 18,263 additions and 12 deletions.
diff --git a/.github/workflows/docs-build.yml b/.github/workflows/docs-build.yml
@@ -0,0 +1,47 @@
+name: docs build
+
+on:
+  # push:
+  #   branches: [ POLARDB_15_STABLE ]
+  #   paths:
+  #     - '.github/workflows/docs*'
+  #     - 'polar-doc/**'
+  pull_request:
+    branches: [ POLARDB_15_STABLE ]
+    paths:
+      - '.github/workflows/docs*'
+      - 'polar-doc/**'
+  # trigger deployment manually
+  workflow_dispatch:
+
+jobs:
+  docs-build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: setup pnpm
+        uses: pnpm/action-setup@v3
+        with:
+          version: 8
+      - name: setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: build VuePress site
+        run: |
+          cd polar-doc
+          pnpm install --frozen-lockfile
+          pnpm docs:build
+
+      # please check out the docs of the workflow for more details
+      # @see https://github.com/crazy-max/ghaction-github-pages
+      - name: Deploy to GitHub Pages
+        uses: crazy-max/ghaction-github-pages@v4
+        if: github.event_name == 'push'
+        with:
+          target_branch: gh-pages
+          build_dir: polar-doc/docs/.vuepress/dist
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
diff --git a/.github/workflows/docs-format-check.yml b/.github/workflows/docs-format-check.yml
@@ -0,0 +1,31 @@
+name: docs format check
+
+on:
+  pull_request:
+    branches: [ POLARDB_15_STABLE ]
+    paths:
+      - ".github/workflows/docs*"
+      - "polar-doc/**"
+  # trigger deployment manually
+  workflow_dispatch:
+
+jobs:
+  docs-format-check:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: setup pnpm
+        uses: pnpm/action-setup@v3
+        with:
+          version: 8
+      - name: setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: prettier check
+        run: |
+          cd polar-doc
+          pnpm install --frozen-lockfile
+          pnpm prettier:check
diff --git a/configure b/configure
@@ -2897,30 +2897,30 @@ _ACEOF
 
 
 POLAR_COMMIT=`git rev-parse --short=8 HEAD || echo unknown`
-POLAR_MAJORVERSION="2.0.$PG_MAJORVERSION"
+POLAR_MAJORVERSION="$PG_MAJORVERSION"
 POLAR_MINORVERSION="2.0" # monthly-version.hotfix
 POLAR_RELEASE_DATE="20240815" # YYYYMMDD
-POLAR_VERSION="$POLAR_MAJORVERSION.$POLAR_MINORVERSION" # eg: 2.0.15.6.2
+POLAR_VERSION="$PACKAGE_VERSION.$POLAR_MINORVERSION" # eg: 15.6.1.2
 POLAR_PG_VERSION="$PACKAGE_VERSION.$POLAR_MINORVERSION" # eg: 15.6.1.2
-POLARDB_VERSION="PolarDB V2.0.$PACKAGE_VERSION.$POLAR_MINORVERSION" # eg: 2.0.15.6.1.2
+POLARDB_VERSION="PolarDB V$PACKAGE_VERSION.$POLAR_MINORVERSION (open)" # eg: 15.6.1.2
 
 cat >>confdefs.h <<_ACEOF
 #define POLAR_COMMIT "$POLAR_COMMIT"
 _ACEOF
 
 
 cat >>confdefs.h <<_ACEOF
-#define POLAR_VERSION "$POLAR_MAJORVERSION.$POLAR_MINORVERSION"
+#define POLAR_VERSION "$POLAR_VERSION"
 _ACEOF
 
 
 cat >>confdefs.h <<_ACEOF
-#define POLAR_PG_VERSION "$PACKAGE_VERSION.$POLAR_MINORVERSION"
+#define POLAR_PG_VERSION "$POLAR_PG_VERSION"
 _ACEOF
 
 
 cat >>confdefs.h <<_ACEOF
-#define POLARDB_VERSION "PolarDB V2.0.$PACKAGE_VERSION.$POLAR_MINORVERSION"
+#define POLARDB_VERSION "$POLARDB_VERSION"
 _ACEOF
 
 

diff --git a/configure.ac b/configure.ac
@@ -43,16 +43,16 @@ PGAC_ARG_REQ(with, extra-version, [STRING], [append STRING to version],
 AC_DEFINE_UNQUOTED(PG_VERSION, "$PG_VERSION", [PostgreSQL version as a string])
 
 POLAR_COMMIT=`git rev-parse --short=8 HEAD || echo unknown`
-POLAR_MAJORVERSION="2.0.$PG_MAJORVERSION"
+POLAR_MAJORVERSION="$PG_MAJORVERSION"
 POLAR_MINORVERSION="2.0" # monthly-version.hotfix
 POLAR_RELEASE_DATE="20240815" # YYYYMMDD
-POLAR_VERSION="$POLAR_MAJORVERSION.$POLAR_MINORVERSION" # eg: 2.0.15.6.2
+POLAR_VERSION="$PACKAGE_VERSION.$POLAR_MINORVERSION" # eg: 15.6.1.2
 POLAR_PG_VERSION="$PACKAGE_VERSION.$POLAR_MINORVERSION" # eg: 15.6.1.2
-POLARDB_VERSION="PolarDB V2.0.$PACKAGE_VERSION.$POLAR_MINORVERSION" # eg: 2.0.15.6.1.2
+POLARDB_VERSION="PolarDB V$PACKAGE_VERSION.$POLAR_MINORVERSION (open)" # eg: 15.6.1.2
 AC_DEFINE_UNQUOTED(POLAR_COMMIT, "$POLAR_COMMIT", [PolarDB commit as a string])
-AC_DEFINE_UNQUOTED(POLAR_VERSION, "$POLAR_MAJORVERSION.$POLAR_MINORVERSION", [PolarDB internal version as a string])
-AC_DEFINE_UNQUOTED(POLAR_PG_VERSION, "$PACKAGE_VERSION.$POLAR_MINORVERSION", [PolarDB PG internal version as a string])
-AC_DEFINE_UNQUOTED(POLARDB_VERSION, "PolarDB V2.0.$PACKAGE_VERSION.$POLAR_MINORVERSION", [PolarDB version as a string])
+AC_DEFINE_UNQUOTED(POLAR_VERSION, "$POLAR_VERSION", [PolarDB internal version as a string])
+AC_DEFINE_UNQUOTED(POLAR_PG_VERSION, "$POLAR_PG_VERSION", [PolarDB PG internal version as a string])
+AC_DEFINE_UNQUOTED(POLARDB_VERSION, "$POLARDB_VERSION", [PolarDB version as a string])
 AC_DEFINE_UNQUOTED(POLAR_RELEASE_DATE, "$POLAR_RELEASE_DATE", [PolarDB release date as a string])
 
 AC_CANONICAL_HOST

diff --git a/polar-doc/.gitignore b/polar-doc/.gitignore
@@ -0,0 +1,7 @@
+# NPM dependencies
+node_modules/
+
+# build artifact
+docs/.vuepress/dist/
+docs/.vuepress/.cache/
+docs/.vuepress/.temp/
diff --git a/polar-doc/Makefile b/polar-doc/Makefile
@@ -0,0 +1,57 @@
+# Makefile
+#	  Makefile for VuePress documentation website of PolarDB.
+#
+# Copyright (c) 2024, Alibaba Group Holding Limited
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# IDENTIFICATION
+#	  polar-doc/Makefile
+
+subdir = polar-doc
+top_builddir = ..
+include $(top_builddir)/src/Makefile.global
+
+all: docs-build
+
+installdirs:
+	$(MKDIR_P) '$(DESTDIR)$(htmldir)'/polar-doc
+
+install:
+	cp -r ./docs/.vuepress/dist/* '$(DESTDIR)$(htmldir)'/polar-doc/
+
+uninstall:
+	rm -rf '$(DESTDIR)$(htmldir)'/polar-doc/*
+
+clean:
+	rm -rf ./docs/.vuepress/dist
+	rm -rf ./docs/.vuepress/.cache
+	rm -rf ./docs/.vuepress/.temp
+
+distclean: clean
+	rm -rf ./node_modules
+
+maintainer-clean: distclean
+
+deps:
+	pnpm install --frozen-lockfile --registry=https://registry.npmmirror.com &>/dev/null
+
+docs-build: deps
+	pnpm run docs:build
+
+docs-dev: deps
+	pnpm run docs:dev
+
+docs-format: deps
+	pnpm run prettier:format
+	pnpm run prettier:format_root
diff --git a/polar-doc/docs/.vuepress/components/ArticleInfo.vue b/polar-doc/docs/.vuepress/components/ArticleInfo.vue
@@ -0,0 +1,95 @@
+<script setup lang="ts">
+import { toRefs } from "vue";
+
+const props = defineProps({
+  frontmatter: {
+    type: Object,
+    required: true,
+  },
+});
+const { frontmatter } = toRefs(props);
+</script>
+
+<style>
+.info_line {
+  display: flex;
+  flex-direction: row;
+  align-items: center;
+}
+
+.container {
+  margin-right: 20px;
+}
+
+.text {
+  color: #999999;
+  margin-left: 5px;
+}
+</style>
+
+<template>
+  <div class="info_line">
+    <div v-if="frontmatter.author" class="info_line container">
+      <svg
+        t="1658821554263"
+        class="icon"
+        viewBox="0 0 1024 1024"
+        version="1.1"
+        xmlns="http://www.w3.org/2000/svg"
+        p-id="12186"
+        width="16"
+        height="16"
+      >
+        <path
+          d="M171.1 861.3c5.9 3.7 12.6 5.6 19.3 5.6 5.3 0 10.7-1.2 15.6-3.6l446.9-215c12-5.8 19.8-17.6 20.4-30.9l8.9-202.6 19.6 12.5c6 3.9 12.7 5.7 19.4 5.7 11.9 0 23.5-5.9 30.3-16.6 10.7-16.7 5.8-39-10.9-49.7L721 354.3l44.3-51.2c6.8-7.9 9.9-18.4 8.4-28.7s-7.4-19.5-16.2-25.1L481.9 72.7c-8.8-5.6-19.6-7.2-29.6-4.2S434 78.6 429.7 88.1l-28 61.6-19.6-12.6c-16.7-10.7-39-5.8-49.7 10.9-10.7 16.7-5.8 39 10.9 49.7l17.8 11.4-181.1 92c-12 6.1-19.5 18.3-19.7 31.7l-5.7 497.7c-0.3 12.5 6 24.1 16.5 30.8z m512.5-573.9L659.8 315 463 189l15.1-33.2 205.5 131.6z m-252.3-33.2l91.2 58.4 89.6 57.4-9.7 222.8-313.1 150.7L431 522.2c24.7 1.1 49.3-10.7 63.6-33 21.4-33.4 11.7-77.7-21.7-99.1s-77.7-11.7-99.1 21.7c-14.3 22.3-14.7 49.5-3.4 71.5L227.9 705.8l4-350.3 199.4-101.3zM896.2 887.2l-704.2 0.1c-19.9 0-36 16.1-36 36s16.1 36 36 36l704.1-0.1c19.9 0 36-16.1 36-36s-16-36-35.9-36zM704.6 761.2c0 19.9 16.1 36 36 36h155.6c19.9 0 36-16.1 36-36s-16.1-36-36-36H740.6c-19.9 0-36 16.2-36 36z"
+          p-id="12187"
+          fill="#999999"
+        ></path>
+      </svg>
+      <p class="text">{{ frontmatter.author }}</p>
+    </div>
+    <div v-if="frontmatter.date" class="info_line container">
+      <svg
+        t="1658821678607"
+        class="icon"
+        viewBox="0 0 1084 1024"
+        version="1.1"
+        xmlns="http://www.w3.org/2000/svg"
+        p-id="14656"
+        width="16"
+        height="16"
+      >
+        <path
+          d="M679.96791406 629.91443867h96.25668487v96.25668399h-96.25668487zM491.78609667 629.91443867h96.25668399v96.25668399h-96.25668398zM303.60427842 629.91443867h96.25668398v96.25668399h-96.25668398zM679.96791406 427.77540107h96.25668487v96.25668487h-96.25668487zM491.78609667 427.77540107h96.25668399v96.25668487h-96.25668398zM303.60427842 427.77540107h96.25668398v96.25668487h-96.25668398z"
+          fill="#999999"
+          p-id="14657"
+        ></path>
+        <path
+          d="M821.94652373 105.79679141h-48.12834199V62h-96.25668398v43.79679141h-89.5187171V62h-96.25668399v43.79679141H398.8983957V62H302.64171084v43.79679141H254.51336885a192.51336885 192.51336885 0 0 0-192.51336885 192.51336885v471.17647089a192.51336885 192.51336885 0 0 0 192.51336885 192.51336885h567.43315488a192.51336885 192.51336885 0 0 0 192.51336973-192.51336885V298.31016026a192.51336885 192.51336885 0 0 0-192.51336973-192.51336885z m96.25668486 663.68983974a96.25668487 96.25668487 0 0 1-96.25668486 96.25668398H254.51336885a96.25668487 96.25668487 0 0 1-96.25668398-96.25668398V298.31016026 293.01604297h759.46523994v5.29411729z"
+          fill="#999999"
+          p-id="14658"
+        ></path>
+      </svg>
+      <p class="text">{{ frontmatter.date }}</p>
+    </div>
+    <div v-if="frontmatter.minute" class="info_line container">
+      <svg
+        t="1658821512864"
+        class="icon"
+        viewBox="0 0 1024 1024"
+        version="1.1"
+        xmlns="http://www.w3.org/2000/svg"
+        p-id="10973"
+        width="16"
+        height="16"
+      >
+        <path
+          d="M836.879252 877.489158l-40.623209 0L796.256042 771.125689c0-59.154261-59.33641-108.910479-115.690906-157.030429-19.591197-16.72594-46.74872-41.527812-56.900941-53.077869l0-98.03478c10.152221-11.550057 37.310767-36.351929 56.900941-53.077869 56.354496-48.119951 115.690906-97.876168 115.690906-157.030429L796.256042 146.509818l40.623209 0c22.426779 0 40.609906-18.183128 40.609906-40.609906S859.306031 65.290005 836.879252 65.290005L187.120748 65.290005c-22.425755 0-40.609906 18.183128-40.609906 40.609906s18.184151 40.609906 40.609906 40.609906l40.596604 0 0 106.36347c0 59.154261 59.33334 108.910479 115.692952 157.030429 19.586081 16.72594 46.747697 41.527812 56.899918 53.077869l0 98.03478c-10.152221 11.550057-37.313837 36.351929-56.899918 53.077869C287.049668 662.21521 227.717352 711.971427 227.717352 771.125689l0 106.36347-40.596604 0c-22.425755 0-40.609906 18.183128-40.609906 40.609906 0 22.426779 18.184151 40.609906 40.609906 40.609906l649.759527 0c22.426779 0 40.609906-18.183128 40.609906-40.609906C877.489158 895.672286 859.306031 877.489158 836.879252 877.489158zM308.937165 771.125689c0-21.703301 57.097416-69.555146 87.207178-95.263667 48.958038-41.794895 85.384669-71.994708 85.384669-110.442368L481.529011 458.580347c0-38.448684-36.426631-68.648496-85.384669-110.442368-30.109762-25.709545-87.207178-73.560366-87.207178-95.263667L308.937165 146.509818l406.099065 0 0 106.36347c0 21.707394-57.100486 69.555146-87.211271 95.263667-48.952922 41.794895-85.381599 71.994708-85.381599 110.442368l0 106.838284c0 38.448684 36.427654 68.648496 85.381599 110.442368 30.109762 25.709545 87.211271 73.556273 87.211271 95.263667l0 106.36347-406.099065 0L308.937165 771.125689zM603.358731 238.027162l0-20.662599c0-19.62599 15.907295-35.533284 35.533284-35.533284 19.62599 0 35.533284 15.908318 35.533284 35.533284l0 20.662599c0 19.62599-15.908318 35.533284-35.533284 35.533284C619.267049 273.560446 603.358731 257.652128 603.358731 238.027162z"
+          p-id="10974"
+          fill="#999999"
+        ></path>
+      </svg>
+      <p class="text">{{ frontmatter.minute }} min</p>
+    </div>
+  </div>
+</template>