Rewrite documentation in Markdown (#219) (#232)

.github/workflows/docs.yml

@@ -0,0 +1,52 @@
+name: docs
+
+on:
+  push:
+    branches: [dev]
+  pull_request:
+    branches: [dev]
+  # trigger deployment manually
+  workflow_dispatch:
+
+defaults:
+  run:
+    shell: bash
+    working-directory: docs
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          # fetch all commits to get last updated time or other git log info
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v1
+        with:
+          # choose node.js version to use
+          node-version: '16'
+
+      # install dependencies if the cache did not hit
+      - name: Install dependencies
+        run: npm ci
+
+      # run build script
+      - name: Build VuePress site
+        run: npm run 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@v2
+        if: github.event_name != 'pull_request'
+        with:
+          # deploy to gh-pages branch
+          target_branch: gh-pages
+          # deploy the default output of VuePress
+          build_dir: docs/.vuepress/dist/Coalesce
+        env:
+          # @see https://docs.github.com/en/actions/reference/authentication-in-a-workflow#about-the-github_token-secret
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -15,6 +15,10 @@ src/Coalesce.Web/output.txt
 # Allow everything in our targets directory, which has a folder named "build" which would otherwise get ignored.
 !src/IntelliTect.Coalesce.CodeGeneration/Analysis/MsBuild/Targets/build/
 
+docs_old/
+#vuepress
+.cache/
+.temp/
 
 
 ## Ignore Visual Studio temporary files, build results, and

docs/.vscode/settings.json

@@ -1,29 +1,3 @@
 {
-  "restructuredtext.languageServer.disabled": false,
-  "restructuredtext.confPath": "${workspaceFolder}",
-  "restructuredtext.linter.sphinxTextRoles": [
-    "csharp",
-    "ts",
-    "ref",
-    "ctor",
-    "html"
-  ],
-  "cSpell.words": [
-    "Axios",
-    "Coalesce's",
-    "POCOs",
-    "Vuetify's",
-    "nameof",
-    "queryable",
-    "readonly",
-    "typeof",
-    "viewmodels",
-    "vuetify"
-  ],
-  "cSpell.ignoreWords": ["datetime"],
   "cSpell.enabled": true,
-  "esbonio.server.enabled": true,
-  "esbonio.sphinx.confDir": "${workspaceFolder}",
-  "restructuredtext.preview.scrollEditorWithPreview": false,
-  "restructuredtext.preview.scrollPreviewWithEditor": false,
-}
+}

docs/.vuepress/components/CodeTabs.vue

@@ -0,0 +1,209 @@
+<template>
+  <div class="code-tabs">
+    <div class="code-tabs__nav">
+      <ul class="code-tabs__ul">
+        <li
+          v-for="(name, shorthand) in actualLanguages"
+          :key="shorthand"
+          class="code-tabs__li"
+        >
+          <button class="code-tabs__nav-tab" 
+          :class="{ 'code-tabs__nav-tab-active': selectedLanguage === shorthand }"
+          :aria-pressed="selectedLanguage === shorthand"
+          :aria-expanded="selectedLanguage === shorthand"
+          @click="switchLanguage(shorthand)"
+          >
+          {{ name }}
+          </button>
+        </li>
+      </ul>
+    </div>
+
+    <div
+      :key="shorthand"
+      v-for="(name, shorthand) in actualLanguages"
+      v-show="shorthand === selectedLanguage"
+      class="code-tabs-item"
+      :class="{ 'code-tabs-item__active': selectedLanguage === shorthand }"
+      :aria-selected="selectedLanguage === shorthand"
+    >
+      <slot :name="shorthand"></slot>
+    </div>
+  </div>
+</template>
+
+
+<style lang="scss">
+
+/**
+ * code-tabs
+ */
+.code-tabs__nav {
+  margin-top: 0.85rem;
+  // 2 * margin + border-radius of <pre> tag
+  margin-bottom: calc(-1.7rem - 6px);
+  padding-bottom: calc(1.7rem - 6px);
+  padding-left: 10px;
+  padding-top: 10px;
+  border-top-left-radius: 6px;
+  border-top-right-radius: 6px;
+  background-color: var(--code-bg-color);
+}
+
+.code-tabs__ul {
+  margin: auto 0px;
+  margin-bottom: 5px;
+  padding-left: 0;
+  display: inline-flex;
+  list-style: none;
+}
+
+.code-tabs__nav-tab {
+  border: 0;
+  padding: 5px 10px;
+  cursor: pointer;
+  background-color: transparent;
+  font-size: 0.90em;
+  line-height: 1.4;
+  color: rgba(255, 255, 255, 0.9);
+  font-weight: 600;
+}
+
+.code-tabs__nav-tab:focus {
+  outline: none;
+}
+
+.code-tabs__nav-tab:focus-visible {
+  outline: 1px solid rgba(255, 255, 255, 0.9);
+}
+
+.code-tabs__nav-tab-active {
+  border-bottom: var(--c-brand) 2px solid;
+}
+
+@media (max-width: 500px) {
+  .code-tabs__nav {
+    margin-left: -1.5rem;
+    margin-right: -1.5rem;
+    border-radius: 0;
+  }
+}
+
+.code-tabs-item {
+  background-color: var(--code-bg-color);
+  div[class*=language-]::before {
+    top: 5px;
+  }
+  
+  // Give some horizontal padding to items that arent code
+  > :not(.line-numbers-mode) {
+    padding: 0 20px
+  }
+
+  pre, pre + div {
+    // Reduce extra whitespace on top
+    padding-top: 8px !important;
+  }
+}
+
+</style>
+
+
+<script>
+// Code tabs plugin inspired by 
+// https://github.com/padarom/vuepress-plugin-code-switcher,
+// updated to work with Vuepress2/Vue3.
+
+import { reactive, effect } from 'vue'
+
+const options = {
+  groups: {
+    default: { vue: "Vue", knockout: "Knockout" },
+    'vue-bundler': { 'vue-cli': 'Vue CLI', vite: 'Vite'}
+  },
+};
+
+const selected = reactive({});
+
+export default {
+  props: {
+    name: {
+      type: String,
+      default: "default",
+    },
+    isolated: {
+      type: Boolean,
+      default: false,
+    },
+    languages: {
+      type: Object,
+      required: false,
+    },
+  },
+
+  data() {
+    return {
+      selectedLanguage: null,
+      actualLanguages: {},
+    };
+  },
+
+  computed: {
+    localStorageKey() {
+      return `vuepress-plugin-code-switcher@${this.name}`;
+    },
+  },
+
+  methods: {
+    switchLanguage(value) {
+      if (this.isolated) {
+        return (this.selectedLanguage = value);
+      }
+
+      if (typeof localStorage !== "undefined") {
+        localStorage.setItem(this.localStorageKey, value);
+      }
+      selected[this.name] = value;
+    },
+
+    setConfiguredDefaultLanguages() {
+      // No need to override the language list if we already have manually
+      // specified languages
+      if (this.languages) {
+        this.actualLanguages = this.languages;
+      } else if (options && options.groups && options.groups[this.name]) {
+        this.actualLanguages = options.groups[this.name];
+      }
+
+      this.selectedLanguage = Object.keys(this.actualLanguages)[0];
+
+      // Set default selected tab for this group
+      if (!selected[this.name]) {
+        selected[this.name] = this.selectedLanguage;
+      }
+    },
+  },
+
+  created() {
+    if (this.isolated) return;
+
+    this.setConfiguredDefaultLanguages();
+    if (!this.actualLanguages) {
+      throw new Error(
+        'You must specify either the "languages" prop or use the "groups" option when configuring the plugin.'
+      );
+    }
+
+    if (typeof localStorage !== "undefined") {
+      let selected = localStorage.getItem(this.localStorageKey);
+      if (
+        selected &&
+        Object.keys(this.actualLanguages).indexOf(selected) !== -1
+      )
+        this.selectedLanguage = selected;
+    }
+
+    effect(() => this.selectedLanguage = selected[this.name] )
+  },
+};
+</script>