Merge pull request ABI-Software#56 from akhuoa/docs

API Documentation

.github/workflows/deploy-docs.yml

@@ -0,0 +1,63 @@
+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 the documentation.
+  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
+
+  # Deploy the documentation.
+  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

@@ -23,3 +23,8 @@ pnpm-debug.log*
 *.njsproj
 *.sln
 *.sw?
+
+# API docs
+docs/.vitepress/dist
+docs/.vitepress/cache
+docs/components

README.md

@@ -45,7 +45,7 @@ You can now use the SimulationVuer in your Vue template as follows:
 <SimulationVuer :apiLocation="apiLocation" :id=123 />
 ```
 
-where `apiLocation` is the URL to the API location and `id` the id of the dataset.
+where `apiLocation` is the URL to the API location and `id` the id of the simulation-based dataset.
 
 ## Project setup
 
@@ -79,3 +79,15 @@ npm run build-bundle
 
 SimulationVuer is now being developed as a Vue 3 component only.
 The [Vue 2 version of SimulationVuer](https://github.com/ABI-Software/simulationvuer/tree/vue2) is not maintained anymore.
+
+## Documentation
+
+The documentation is written using [VitePress](https://vitepress.dev/) and [vuese](https://github.com/vuese/vuese#readme), and it can be found in the `docs` folder.
+
+#### To run in local development mode
+
+```bash
+npm run docs:watch
+```
+
+This will start the documentation server with [VitePress](https://vitepress.dev/) on port `5173`: http://localhost:5173/simulationvuer/.

docs/.vitepress/config.js

@@ -0,0 +1,68 @@
+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: "SimulationVuer",
+  description: "API documentation for SimulationVuer",
+  base: '/simulationvuer/',
+  themeConfig: {
+    // https://vitepress.dev/reference/default-theme-config
+    nav: [
+      { text: 'Home', link: '/' },
+      {
+        text: 'API Reference',
+        link: '/components/SimulationVuer'
+      }
+    ],
+
+    sidebar: [
+      {
+        text: 'Live Demo',
+        link: '/demo'
+      },
+      {
+        text: 'API Reference',
+        link: '/components/SimulationVuer'
+      },
+      {
+        text: 'Version',
+        items: [
+          {
+            text: `${versionNumber}`
+          }
+        ]
+      }
+    ],
+
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/ABI-Software/simulationvuer' }
+    ]
+  },
+  markdown: { attrs: { disable: true } },
+  vite: {
+    css: {
+      preprocessorOptions: {
+        scss: {
+          additionalData: `@use '../src/assets/styles' as *;`
+        },
+      },
+    },
+    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/demo-styles.css

@@ -0,0 +1,29 @@
+.demo-map-container {
+  width: 100%;
+  height: 0;
+  padding-bottom: 75%;
+  border: 1px solid var(--vp-c-divider);
+  position: relative;
+  z-index: 1; /* Just for the demo, to prevent tooltips from going out of the container. */
+}
+
+.demo-map-container-inner {
+  width: 100%;
+  height: 100%;
+  position: absolute;
+}
+
+.flatmap-container {
+  overflow: hidden;
+}
+
+.bottom-right-control {
+  display: flex;
+  flex-direction: row;
+  gap: 8px;
+}
+
+.zoomOut,
+.fitWindow {
+  padding-left: 0px !important;
+}

docs/demo.md

@@ -0,0 +1,59 @@
+# SimulationVuer Live Demo
+
+## Live Demo
+
+<div class="demo-map-container">
+  <div class="demo-map-container-inner">
+    <ClientOnly>
+      <SimulationVuer
+        :apiLocation="apiLocation"
+        :id="id"
+      />
+    </ClientOnly>
+  </div>
+</div>
+
+<script setup>
+import { defineClientComponent } from "vitepress";
+import "./demo-styles.css";
+
+const SimulationVuer = defineClientComponent(() => {
+  return import("../src/components/SimulationVuer.vue");
+})
+</script>
+
+<script>
+export default {
+  data: function() {
+    return {
+      apiLocation: import.meta.env.VITE_API_LOCATION,
+      id: 135,
+    };
+  }
+}
+</script>
+
+## Code Preview
+
+```js-vue
+  <div class="your-outer-container">
+    <SimulationVuer
+      :apiLocation="apiLocation"
+      :id="id"
+    />
+  </div>
+
+  <script>
+    import { SimulationVuer } from "@abi-software/simulationvuer";
+
+    export default {
+      components: { SimulationVuer },
+      data: function () {
+        return {
+          apiLocation: API_LOCATION,
+          id: 135,
+        }
+      }
+    }
+  </script>
+```

docs/index.md

@@ -0,0 +1,16 @@
+---
+# https://vitepress.dev/reference/default-theme-home-page
+layout: home
+
+hero:
+  name: "SimulationVuer"
+  text: "API documentation"
+  tagline: SimulationVuer is a Vue component used in the SPARC portal to run some simulation-based datasets.
+  actions:
+    - theme: brand
+      text: API Reference
+      link: /components/SimulationVuer
+    - theme: alt
+      text: Demo
+      link: /demo
+---