Merge pull request #9 from akhuoa/docs

API Documentation

.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

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

README.md

@@ -45,7 +45,7 @@ export default {
 /* eslint-disable no-alert, no-console */
 import { MapSvgIcon } from '@abi-software/svg-sprite';
 import "@abi-software/svg-sprite/dist/style.css";
-``` 
+```
 
 ### Change the icon colours
 ```
@@ -54,7 +54,7 @@ import "@abi-software/svg-sprite/dist/style.css";
   color: red;
 }
 </style>
-``` 
+```
 
 ## Customize configuration
 
@@ -70,13 +70,24 @@ npm install
 npm run serve
 ```
 
-### Create bundle for npm and publish 
+### Create bundle for npm and publish
 ```
 npm run build-bundle
-npm publish 
+npm publish
 ```
 
 ### Lints and fixes files
 ```
 npm run lint
 ```
+
+## 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,87 @@
+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: "MapSvgSprite",
+  description: "API documentation for MapSvgSprite",
+  base: '/svg-sprite/',
+  themeConfig: {
+    // https://vitepress.dev/reference/default-theme-config
+    nav: [
+      { text: 'Home', link: '/' },
+      {
+        text: 'API Reference',
+        link: '/components/SvgSprite'
+      }
+    ],
+
+    sidebar: [
+      {
+        text: 'Live Demo',
+        link: '/demo'
+      },
+      {
+        text: 'API Reference',
+        items: [
+          {
+            text: 'SvgSprite',
+            link: '/components/SvgSprite'
+          },
+          {
+            text: 'SvgSpriteColor',
+            link: '/components/SvgSpriteColor'
+          },
+          {
+            text: 'SvgIcon',
+            link: '/components/SvgIcon'
+          }
+        ]
+      },
+      {
+        text: 'Version',
+        items: [
+          {
+            text: `${versionNumber}`
+          }
+        ]
+      }
+    ],
+
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/ABI-Software/svg-sprite' }
+    ]
+  },
+  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/demo-styles.css

@@ -0,0 +1,36 @@
+.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;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.mapcontent {
+  overflow: hidden;
+
+  & .dialog-header {
+    color: #8300BF !important;
+  }
+}
+
+.bottom-right-control {
+  display: flex;
+  flex-direction: row;
+  gap: 8px;
+}
+
+.zoomOut,
+.fitWindow {
+  padding-left: 0px !important;
+}

docs/demo.md

@@ -0,0 +1,52 @@
+# MapSvgSprite Live Demo
+
+## Live Demo
+
+<div class="demo-map-container">
+  <div class="demo-map-container-inner">
+    <ClientOnly>
+      <MapSvgSpriteColor />
+      <p>Magnifying Glass Icon</p>
+      &nbsp;
+      <MapSvgIcon
+        icon="magnifyingGlass"
+      />
+      <MapSvgSprite />
+    </ClientOnly>
+  </div>
+</div>
+
+<script setup>
+import { defineClientComponent } from "vitepress";
+import "./demo-styles.css";
+
+const MapSvgSpriteColor = defineClientComponent(() => {
+  return import("../src/components/SvgSpriteColor.vue");
+})
+const MapSvgIcon = defineClientComponent(() => {
+  return import("../src/components/SvgIcon.vue");
+})
+const MapSvgSprite = defineClientComponent(() => {
+  return import("../src/components/SvgSprite.vue");
+})
+</script>
+
+
+## Code Preview
+
+```js-vue
+  <div class="your-outer-container">
+    Magnifying Glass Icon
+    <MapSvgIcon
+      icon="magnifyingGlass"
+    />
+  </div>
+
+  <script>
+    import { MapSvgIcon } from '@abi-software/svg-sprite';
+
+    export default {
+      components: { MapSvgIcon }
+    }
+  </script>
+```

docs/index.md

@@ -0,0 +1,16 @@
+---
+# https://vitepress.dev/reference/default-theme-home-page
+layout: home
+
+hero:
+  name: "MapSvgSprite"
+  text: "API documentation"
+  tagline:
+  actions:
+    - theme: brand
+      text: API Reference
+      link: /components/SvgSprite
+    - theme: alt
+      text: Demo
+      link: /demo
+---