Merge pull request #9 from Carifio24/docs

Add documentation to composables and utility functions

Author: Carifio24

.github/workflows/build-deploy-docs.yml

@@ -0,0 +1,46 @@
+name: Build and Deploy Docs
+
+on:
+  push:
+    branches:
+      main
+
+permissions: read-all
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+          ref: ${{ github.event.pull_request.head.sha }}
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '20.x'
+
+      - name: Set up yarn
+        run: corepack enable && yarn set version 3.3.0
+
+      - name: Install
+        run: yarn install
+
+      - name: Lint
+        run: yarn lint
+
+      - name: Build
+        run: yarn build
+
+      - name: Build docs
+        run: yarn docs
+
+      - name: Deploy docs to GitHub Pages
+        uses: JamesIves/github-pages-deploy-action@v4
+        if: ${{ steps.draft.outputs.value }} == 'true'
+        with:
+          branch: gh-pages
+          folder: docs 
+

.github/workflows/build.yml

@@ -33,3 +33,7 @@ jobs:
 
       - name: Build
         run: yarn build
+
+      - name: Build docs
+        run: yarn docs
+

.gitignore

@@ -24,3 +24,5 @@ tsconfig.tsbuildinfo
 **/tests_output/**
 
 *.env
+
+docs/

package.json

@@ -29,6 +29,8 @@
     "eslint-plugin-vue": "^9.8.0",
     "less": "^4.2.0",
     "less-loader": "^12.1.0",
+    "typedoc": "^0.25.13",
+    "typedoc-plugin-vue": "^1.1.0",
     "typescript": "^4.9.4",
     "vue-template-compiler": "^2.7.14",
     "webpack": "^5.75.0"
@@ -46,6 +48,7 @@
   "scripts": {
     "build": "vue-cli-service build --target lib --name index src/index.ts",
     "clean": "rimraf dist",
+    "docs": "typedoc",
     "lint": "vue-cli-service lint src --no-fix"
   },
   "types": "./dist/src/index.d.ts"

src/background.ts

@@ -1,5 +1,8 @@
+/** Class representing a background imageset for WorldWide Telescope */
 export class BackgroundImageset {
+  /** The outward-facing name to use for the imageset in a story */
   public imagesetName: string;
+  /** The name of the imageset object inside WorldWide Telescope */
   public displayName: string;
 
   constructor(displayName: string, imagesetName: string) {
@@ -8,6 +11,7 @@ export class BackgroundImageset {
   }
 }
 
+/** A default list of `BackgroundImagset` objects to use within data stories */
 export const skyBackgroundImagesets: BackgroundImageset[] = [
   new BackgroundImageset(
     "Optical (Terapixel DSS)",

src/components/CreditLogos.vue

@@ -23,7 +23,6 @@ import { computed } from "vue";
 import { CreditLogosProps } from "../types";
 
 const props = withDefaults(defineProps<CreditLogosProps>(), {
-  visible: true,
   logoSize: "5vmin"
 });
 

src/components/GeolocationButton.vue

@@ -59,7 +59,6 @@ import { GeolocationButtonProps } from "../types";
 
 const props = withDefaults(defineProps<GeolocationButtonProps>(), {
   color: "white",
-  disabled: false,
   size: "small",
   density: "comfortable",
   elevation: "2",
@@ -73,7 +72,6 @@ const props = withDefaults(defineProps<GeolocationButtonProps>(), {
   label: "My Location",
   trueIcon: "mdi-crosshairs-gps",
   falseIcon: "mdi-crosshairs",
-  backgroundColor: "black",
   showPermissions: false,
 });
 

src/composables.ts

@@ -1,6 +1,10 @@
 import { ref, onMounted, onUnmounted, Ref } from "vue";
 import screenfull from "screenfull";
 
+/**
+  * A composable that encapsulates fullscreen behavior.
+  * @returns A reactive variable indicating whether or not fullscreen mode is active
+  */ 
 export function useFullscreen(): Ref<boolean> {
   const fullscreenModeActive = ref(false);
   function update(_event: Event) {
@@ -22,11 +26,20 @@ export function useFullscreen(): Ref<boolean> {
   return fullscreenModeActive;
 }
 
+/** Interface describing the shape of a browser window */
 export interface WindowShape {
   width: number;
   height: number;
 }
+
+/** A default `WindowShape` to use */
 export const defaultWindowShape = { width: 1200, height: 900 };
+
+/**
+  * A composable that encapsulates a changing window shape.
+  *
+  * @returns A reactive variable describing the current window shape.
+  */
 export function useWindowShape() {
   const windowShape = ref<WindowShape>(defaultWindowShape);
   const resizeObserver = new ResizeObserver(_entries => update());
@@ -51,6 +64,6 @@ export function useWindowShape() {
     resizeObserver.unobserve(document.body);
   });
 
-  return { windowShape, resizeObserver };
+  return windowShape;
 }
 

src/geolocation.ts

@@ -2,6 +2,11 @@ import { ref, onMounted } from "vue";
 import { Capacitor, PermissionState as CapacitorPermissionState } from '@capacitor/core';
 import { Geolocation, PermissionStatus as CapacitorPermissionStatus, Position, PositionOptions } from "@capacitor/geolocation";
 
+/**
+  * Determine which of two capacitor permission states is 'better'.
+  * This implementation takes "prompt-with-rationale" to be better than "prompt".
+  * @returns The 'better' of the two input permission states
+  */
 function betterPermissionState(firstState: CapacitorPermissionState, secondState: CapacitorPermissionState): CapacitorPermissionState {
   const states: CapacitorPermissionState[] = ["granted", "prompt-with-rationale", "prompt", "denied"];
   for (const state of states) {
@@ -13,6 +18,13 @@ function betterPermissionState(firstState: CapacitorPermissionState, secondState
 }
 
 export type PositionCoords = Position['coords'];
+
+/**
+  * A composable that encapsulates the current state of the browser
+  * geolocation position and permission status.
+  * @param onStartup - Whether or not to query the user's geolocation on startup.
+  * @returns Reactive state describing the geolocation
+  */
 export function useGeolocation(onStartup=true) {
 
   const geolocation = ref<PositionCoords | null>(null);

src/index.ts

@@ -1,7 +1,7 @@
 import { BackgroundImageset, skyBackgroundImagesets } from "./background";
 import { useFullscreen, useWindowShape, WindowShape } from "./composables";
 import { PositionCoords, useGeolocation } from "./geolocation";
-import { KeyboardControlSettings } from "./keyboard";
+import { KeyPressInfo, KeyboardControlSettings } from "./keyboard";
 import { useWWTKeyboardControls } from "./wwt-utils";
 
 import IconButton from "./components/IconButton.vue";
@@ -15,6 +15,7 @@ import Gallery from "./components/Gallery.vue";
 
 export {
   BackgroundImageset,
+  KeyPressInfo,
   KeyboardControlSettings,
   Gallery,
   IconButton,