Merge pull request #68 from akhuoa/docs

API Documentation

.env

@@ -1,5 +1,8 @@
-VUE_APP_API_LOCATION=http://localhost:5000/
-VUE_APP_ALGOLIA_INDEX=k-core_dev_published_time_desc
-VUE_APP_ALGOLIA_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-VUE_APP_ALGOLIA_ID=xxxxxxxxx
-VUE_APP_PENNSIEVE_API_LOCATION=https://api.pennsieve.io
+VITE_APP_API_LOCATION=http://localhost:5000/
+VITE_FLATMAPAPI_LOCATION=''
+VITE_APP_ALGOLIA_KEY=
+VITE_APP_ALGOLIA_ID=
+VITE_APP_PENNSIEVE_API_LOCATION=https://api.pennsieve.io
+VITE_APP_ALGOLIA_INDEX=k-core_dev_published_time_desc
+VITE_APP_NL_LINK_PREFIX=
+VITE_APP_ROOT_URL=

.github/workflows/deploy-docs.yml

@@ -0,0 +1,59 @@
+name: Deploy Docs to Pages
+
+on:
+  # Runs on pushes targeting the `docs` branch and `main` branch.
+  push:
+    branches: ["docs", "main"]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+# concurrency:
+#   group: pages
+#   cancel-in-progress: false
+
+jobs:
+  # Build job
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '18.17.1'
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build with VitePress
+        run: |
+          npm run docs:build
+          touch docs/.vitepress/dist/.nojekyll
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./docs/.vitepress/dist
+
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to Github Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -1,4 +1,7 @@
 .DS_Store
 dist
 node_modules
-.env.local
+.env.local
+docs/.vitepress/dist
+docs/.vitepress/cache
+docs/components

README.md

@@ -45,7 +45,7 @@ import "@abi-software/map-side-bar/dist/style.css";
 The code in template should looks like this
 
 ```html
-<SideBar 
+<SideBar
   :envVars="envVars"
   :visible="sideBarVisibility"
   @actionClick="actionClick"
@@ -112,7 +112,7 @@ README = 'readme'
 TITLE = 'title'
 ```
 
-Note: All are optional except for ‘name’ 
+Note: All are optional except for ‘name’
 
 ### Sidebar input processing
 Sidebar input processing can be viewed here:
@@ -146,7 +146,7 @@ All fields are strings:
       "path": required // relative path to the view file, eg "derivative\\Scaffolds\\scaffoldMap_tenial_view.json",
       "sample": optional // used to link to views to samples
       "thumbnail": optional // technically optional but it won’t look great
-    } 
+    }
   ]
 }
 ```
@@ -155,4 +155,14 @@ An example context card file can be viewed here:
 https://drive.google.com/file/d/15NVRBny7WGltpMSRbsgMglXo0xOC3-Q9/view?usp=sharing
 
 
+## API Documentation
+
+The API documentation is developed with `vitepress` and `vuese`. Documentation pages are in the `docs` folder.
+
+### To run in local development mode
+```bash
+npm run docs:watch
+```
+
+This will start the documentation server with `vitepress` on port `:5173` and watch the components' changes.
 

docs/.vitepress/config.js

@@ -0,0 +1,74 @@
+import path from 'path'
+import { defineConfig } from 'vitepress'
+import Components from 'unplugin-vue-components/vite'
+import { ElementPlusResolver } from 'unplugin-vue-components/resolvers'
+
+const versionNumber = process.env.npm_package_version
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+  title: "SideBar",
+  description: "API documentation for SideBar",
+  base: '/map-sidebar/',
+  themeConfig: {
+    // https://vitepress.dev/reference/default-theme-config
+    nav: [
+      { text: 'Home', link: '/' },
+      {
+        text: 'API Reference',
+        link: '/components/SideBar'
+      }
+    ],
+
+    sidebar: [
+      {
+        text: 'Live Demo',
+        link: '/demo'
+      },
+      {
+        text: 'API Reference',
+        link: '/components/SideBar'
+      },
+      {
+        text: 'Version',
+        items: [
+          {
+            text: `${versionNumber}`
+          }
+        ]
+      }
+    ],
+
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/ABI-Software/map-sidebar' }
+    ]
+  },
+  markdown: { attrs: { disable: true } },
+  vite: {
+    css: {
+      preprocessorOptions: {
+        scss: {
+          additionalData: `@use '../src/assets/styles' as *;`
+        },
+      },
+    },
+    resolve: {
+      alias: {
+        '@': path.resolve(__dirname, '../../src'),
+      }
+    },
+    plugins: [
+      Components({
+        // Allow auto load markdown components under `./src/components/`.
+        extensions: ['vue'],
+        // Allow auto import and register the components used in markdown.
+        include: [/\.vue$/, /\.vue\?vue/],
+        resolvers: [
+          ElementPlusResolver({
+            importStyle: 'css',
+          }),
+        ],
+      }),
+    ]
+  }
+})

docs/.vitepress/theme/custom.css

@@ -0,0 +1,58 @@
+/* Modify content styles for the desktop view. */
+@media (min-width: 1280px) {
+  .VPContent .VPDoc.has-aside {
+    & .content-container {
+      max-width: none;
+    }
+
+    .content-container .vp-doc {
+      & table {
+        overflow: unset;
+      }
+
+      & table thead {
+        position: sticky;
+        top: 64px; /* Navigation height. */
+
+        & th {
+          background-color: var(--vp-c-gray-1);
+        }
+      }
+
+      & table tr {
+        th, td {
+          vertical-align: top;
+        }
+
+        th:first-child,
+        td:first-child {
+          width: 10%;
+          text-wrap: nowrap;
+        }
+
+        /* Description column. */
+        th:nth-child(2),
+        td:nth-child(2) {
+          width: 40%;
+        }
+
+        th:nth-child(3),
+        td:nth-child(3) {
+          width: 10%;
+        }
+
+        th:nth-child(4),
+        td:nth-child(4) {
+          width: 10%;
+        }
+
+        th:last-child,
+        td:last-child {
+          width: 20%;
+          word-wrap: break-word;
+          word-break: break-word;
+        }
+      }
+    }
+  }
+}

docs/.vitepress/theme/index.js

@@ -0,0 +1,4 @@
+import DefaultTheme from "vitepress/theme";
+import "./custom.css";
+
+export default DefaultTheme;

docs/components.d.ts

@@ -0,0 +1,27 @@
+/* eslint-disable */
+/* prettier-ignore */
+// @ts-nocheck
+// Generated by unplugin-vue-components
+// Read more: https://github.com/vuejs/core/pull/3399
+export {}
+
+declare module 'vue' {
+  export interface GlobalComponents {
+    ElButton: typeof import('element-plus/es')['ElButton']
+    ElCard: typeof import('element-plus/es')['ElCard']
+    ElCascader: typeof import('element-plus/es')['ElCascader']
+    ElDrawer: typeof import('element-plus/es')['ElDrawer']
+    ElIcon: typeof import('element-plus/es')['ElIcon']
+    ElIconArrowLeft: typeof import('@element-plus/icons-vue')['ArrowLeft']
+    ElIconArrowRight: typeof import('@element-plus/icons-vue')['ArrowRight']
+    ElInput: typeof import('element-plus/es')['ElInput']
+    ElOption: typeof import('element-plus/es')['ElOption']
+    ElPagination: typeof import('element-plus/es')['ElPagination']
+    ElPopover: typeof import('element-plus/es')['ElPopover']
+    ElSelect: typeof import('element-plus/es')['ElSelect']
+    ElTag: typeof import('element-plus/es')['ElTag']
+  }
+  export interface ComponentCustomProperties {
+    vLoading: typeof import('element-plus/es')['ElLoadingDirective']
+  }
+}

docs/demo-styles.css

@@ -0,0 +1,40 @@
+.demo-map-container {
+  width: 100%;
+  height: 0;
+  padding-bottom: 75%;
+  border: 1px solid var(--vp-c-divider);
+  position: relative;
+  z-index: 1; /* just for demo, to prevent tooltips go out of container */
+}
+
+.demo-map-container-inner {
+  width: 100%;
+  height: 100%;
+  position: absolute;
+
+  & iframe {
+    display: block;
+    width: 100%;
+    height: 100%;
+    border: none;
+  }
+}
+
+.mapcontent {
+  overflow: hidden;
+
+  & .dialog-header {
+    color: #8300BF !important;
+  }
+}
+
+.bottom-right-control {
+  display: flex;
+  flex-direction: row;
+  gap: 8px;
+}
+
+.zoomOut,
+.fitWindow {
+  padding-left: 0px !important;
+}