docs: add the typedoc

hrgui · hrgui · commit ef45335fad1f · 2025-02-21T00:06:05.000-08:00
diff --git a/bun.lockb b/bun.lockb
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
@@ -1,4 +1,5 @@
 import { defineConfig } from "vitepress";
+import typedocSidebar from "../api/typedoc-sidebar.json";
 
 // https://vitepress.dev/reference/site-config
 export default defineConfig({
@@ -7,7 +8,16 @@ export default defineConfig({
   description: "A NPM package to transpose and manage chord charts for music",
   themeConfig: {
     // https://vitepress.dev/reference/default-theme-config
-    nav: [{ text: "Demo", link: "/" }],
+    nav: [
+      { text: "Demo", link: "/" },
+      { text: "API", link: "/api/" },
+    ],
     socialLinks: [{ icon: "github", link: "https://github.com/hrgui/chord-charts" }],
+    sidebar: [
+      {
+        text: "API",
+        items: typedocSidebar,
+      },
+    ],
   },
 });
diff --git a/docs/api/functions/allChords.md b/docs/api/functions/allChords.md
@@ -0,0 +1,27 @@
+[@hrgui/chord-charts](../globals.md) / allChords
+
+# Function: allChords()
+
+> **allChords**(`input`, `opts`): `RegExpMatchArray`
+
+Defined in: [index.ts:132](https://github.com/hrgui/chord-charts/blob/5945fa3cca5e7a9fbbe3cd4a4803e60977033ca0/src/index.ts#L132)
+
+Extras only the chords from the input string
+
+## Parameters
+
+### input
+
+`string`
+
+given a chord chart
+
+### opts
+
+[`InputOptions`](../type-aliases/InputOptions.md) & `object` = `{}`
+
+Input Options, including sort
+
+## Returns
+
+`RegExpMatchArray`
diff --git a/docs/api/functions/tranposeChord.md b/docs/api/functions/tranposeChord.md
@@ -0,0 +1,33 @@
+[@hrgui/chord-charts](../globals.md) / tranposeChord
+
+# Function: tranposeChord()
+
+> **tranposeChord**(`chord`, `originalKey`, `targetKey`): `string`
+
+Defined in: [index.ts:171](https://github.com/hrgui/chord-charts/blob/5945fa3cca5e7a9fbbe3cd4a4803e60977033ca0/src/index.ts#L171)
+
+Transposes a single chord
+
+## Parameters
+
+### chord
+
+`string`
+
+chord to transpose, e.g. Dm7
+
+### originalKey
+
+`string`
+
+the original key the chord was in
+
+### targetKey
+
+`string`
+
+the target key to transpose the chord to
+
+## Returns
+
+`string`
diff --git a/docs/api/functions/transpose.md b/docs/api/functions/transpose.md
@@ -0,0 +1,33 @@
+[@hrgui/chord-charts](../globals.md) / transpose
+
+# Function: transpose()
+
+> **transpose**(`input`, `originalKey`, `targetKey`): `string`
+
+Defined in: [index.ts:160](https://github.com/hrgui/chord-charts/blob/5945fa3cca5e7a9fbbe3cd4a4803e60977033ca0/src/index.ts#L160)
+
+Transposes a chord chart to a new key
+
+## Parameters
+
+### input
+
+`string`
+
+chord chart
+
+### originalKey
+
+`string`
+
+the original key the chord chart was in
+
+### targetKey
+
+`string`
+
+the target key to transpose the chord chart to
+
+## Returns
+
+`string`
diff --git a/docs/api/functions/uniqueChords.md b/docs/api/functions/uniqueChords.md
@@ -0,0 +1,23 @@
+[@hrgui/chord-charts](../globals.md) / uniqueChords
+
+# Function: uniqueChords()
+
+> **uniqueChords**(`input`, `opts`): `string`[]
+
+Defined in: [index.ts:149](https://github.com/hrgui/chord-charts/blob/5945fa3cca5e7a9fbbe3cd4a4803e60977033ca0/src/index.ts#L149)
+
+Shows the unique chords of a chord chart, used to establish a key
+
+## Parameters
+
+### input
+
+`string`
+
+### opts
+
+[`InputOptions`](../type-aliases/InputOptions.md) = `{}`
+
+## Returns
+
+`string`[]
diff --git a/docs/api/functions/wrap.md b/docs/api/functions/wrap.md
@@ -0,0 +1,25 @@
+[@hrgui/chord-charts](../globals.md) / wrap
+
+# Function: wrap()
+
+> **wrap**(`input`, `fn`, `opts`): `string`
+
+Defined in: [index.ts:122](https://github.com/hrgui/chord-charts/blob/5945fa3cca5e7a9fbbe3cd4a4803e60977033ca0/src/index.ts#L122)
+
+## Parameters
+
+### input
+
+`string`
+
+### fn
+
+(`str`) => `any`
+
+### opts
+
+[`InputOptions`](../type-aliases/InputOptions.md) = `{}`
+
+## Returns
+
+`string`
diff --git a/docs/api/globals.md b/docs/api/globals.md
@@ -0,0 +1,18 @@
+# @hrgui/chord-charts
+
+## Type Aliases
+
+- [InputOptions](type-aliases/InputOptions.md)
+- [Key](type-aliases/Key.md)
+
+## Variables
+
+- [keys](variables/keys.md)
+
+## Functions
+
+- [allChords](functions/allChords.md)
+- [tranposeChord](functions/tranposeChord.md)
+- [transpose](functions/transpose.md)
+- [uniqueChords](functions/uniqueChords.md)
+- [wrap](functions/wrap.md)
diff --git a/docs/api/index.md b/docs/api/index.md
@@ -0,0 +1,26 @@
+# @hrgui/chord-charts
+
+A package that helps manage and transpose Guitar chord charts.
+
+# Usage
+
+```ts
+import { transpose } from "@hrgui/chord-charts";
+
+console.log(
+  transpose(
+    `
+       D            G          D
+Amazing Grace, how sweet the sound,
+			 A7
+That saved a wretch like me.
+     D                G       D
+I once was lost, but now im found,
+               A7     D
+Was blind, but now I see.
+`,
+    "D",
+    "C",
+  ),
+);
+```
diff --git a/docs/api/type-aliases/InputOptions.md b/docs/api/type-aliases/InputOptions.md
@@ -0,0 +1,15 @@
+[@hrgui/chord-charts](../globals.md) / InputOptions
+
+# Type Alias: InputOptions
+
+> **InputOptions**: `object`
+
+Defined in: [index.ts:99](https://github.com/hrgui/chord-charts/blob/5945fa3cca5e7a9fbbe3cd4a4803e60977033ca0/src/index.ts#L99)
+
+## Type declaration
+
+### ignorecase?
+
+> `optional` **ignorecase**: `boolean`
+
+Ignores case
diff --git a/docs/api/type-aliases/Key.md b/docs/api/type-aliases/Key.md
@@ -0,0 +1,27 @@
+[@hrgui/chord-charts](../globals.md) / Key
+
+# Type Alias: Key
+
+> **Key**: `object`
+
+Defined in: [index.ts:1](https://github.com/hrgui/chord-charts/blob/5945fa3cca5e7a9fbbe3cd4a4803e60977033ca0/src/index.ts#L1)
+
+## Type declaration
+
+### name
+
+> **name**: `string`
+
+Name of the key, e.g. Ab, A, A#
+
+### type
+
+> **type**: `"F"` \| `"N"` \| `"S"`
+
+F = Flat, N = Neutral, S = Sharp
+
+### value
+
+> **value**: `number`
+
+Value, starts from 0 and ends at 11 (chromatic scale)
diff --git a/docs/api/typedoc-sidebar.json b/docs/api/typedoc-sidebar.json
@@ -0,0 +1 @@
+[{"text":"Type Aliases","collapsed":true,"items":[{"text":"InputOptions","link":"/api/type-aliases/InputOptions.md"},{"text":"Key","link":"/api/type-aliases/Key.md"}]},{"text":"Variables","collapsed":true,"items":[{"text":"keys","link":"/api/variables/keys.md"}]},{"text":"Functions","collapsed":true,"items":[{"text":"allChords","link":"/api/functions/allChords.md"},{"text":"tranposeChord","link":"/api/functions/tranposeChord.md"},{"text":"transpose","link":"/api/functions/transpose.md"},{"text":"uniqueChords","link":"/api/functions/uniqueChords.md"},{"text":"wrap","link":"/api/functions/wrap.md"}]}]
diff --git a/docs/api/variables/keys.md b/docs/api/variables/keys.md
@@ -0,0 +1,9 @@
+[@hrgui/chord-charts](../globals.md) / keys
+
+# Variable: keys
+
+> `const` **keys**: [`Key`](../type-aliases/Key.md)[]
+
+Defined in: [index.ts:11](https://github.com/hrgui/chord-charts/blob/5945fa3cca5e7a9fbbe3cd4a4803e60977033ca0/src/index.ts#L11)
+
+All keys, including flats, neutral and sharp
diff --git a/docs/bun.lockb b/docs/bun.lockb
diff --git a/package.json b/package.json
@@ -23,7 +23,8 @@
     "build": "vite build",
     "lint": "bun tsc --noEmit",
     "test": "vitest",
-    "prepare": "./node_modules/.bin/husky"
+    "prepare": "./node_modules/.bin/husky",
+    "typedoc": "bunx typedoc --exclude \"**/*+(index|.spec|.e2e|.test).ts\" --entryPointStrategy Expand src"
   },
   "devDependencies": {
     "@types/node": "^22.13.4",
@@ -32,6 +33,9 @@
     "jsdom": "^26.0.0",
     "lint-staged": "^15.4.3",
     "prettier": "^3.5.1",
+    "typedoc": "^0.27.7",
+    "typedoc-plugin-markdown": "^4.4.2",
+    "typedoc-vitepress-theme": "^1.1.2",
     "typescript": "^5.7.3",
     "vite": "^6.1.0",
     "vite-plugin-dts": "^4.5.0",
diff --git a/src/index.test.ts b/src/index.test.ts
@@ -57,7 +57,7 @@ describe("uniqueChords", () => {
   });
 });
 
-describe("tranpose", () => {
+describe("transpose", () => {
   it("should be able to transpose a song down a key", () => {
     expect(transpose(amazingGraceInput, "D", "C")).toMatchInlineSnapshot(`
       "
diff --git a/src/index.ts b/src/index.ts
@@ -1,9 +1,13 @@
 export type Key = {
+  /** Name of the key, e.g. Ab, A, A# */
   name: string;
+  /** Value, starts from 0 and ends at 11 (chromatic scale) */
   value: number;
+  /** F = Flat, N = Neutral, S = Sharp */
   type: "F" | "N" | "S";
 };
 
+/** All keys, including flats, neutral and sharp */
 export const keys: Key[] = [
   {
     name: "Ab",
@@ -92,7 +96,10 @@ export const keys: Key[] = [
   },
 ];
 
-export type InputOptions = { ignorecase?: boolean };
+export type InputOptions = {
+  /** Ignores case */
+  ignorecase?: boolean;
+};
 
 const chordRegex =
   // Word boundary followed by a root chord
@@ -116,6 +123,12 @@ export function wrap(input: string, fn: (str) => any, opts: InputOptions = {}) {
   return input.replace(new RegExp(chordRegex, opts.ignorecase ? "gi" : "g"), fn);
 }
 
+/**
+ * Extras only the chords from the input string
+ * @param input given a chord chart
+ * @param opts Input Options, including sort
+ * @returns
+ */
 export function allChords(input: string, opts: InputOptions & { sort?: boolean } = {}) {
   const matches = input.match(new RegExp(chordRegex, opts.ignorecase ? "gi" : "g"));
   return opts.sort
@@ -127,14 +140,34 @@ export function allChords(input: string, opts: InputOptions & { sort?: boolean }
     : matches;
 }
 
+/**
+ * Shows the unique chords of a chord chart, used to establish a key
+ * @param input
+ * @param opts
+ * @returns
+ */
 export function uniqueChords(input: string, opts: InputOptions = {}) {
   return Array.from(new Set(allChords(input, opts)));
 }
 
+/**
+ * Transposes a chord chart to a new key
+ * @param input chord chart
+ * @param originalKey the original key the chord chart was in
+ * @param targetKey the target key to transpose the chord chart to
+ * @returns
+ */
 export function transpose(input: string, originalKey: string, targetKey: string) {
   return wrap(input, (chord) => tranposeChord(chord, originalKey, targetKey));
 }
 
+/**
+ * Transposes a single chord
+ * @param chord chord to transpose, e.g. Dm7
+ * @param originalKey the original key the chord was in
+ * @param targetKey the target key to transpose the chord to
+ * @returns
+ */
 export function tranposeChord(chord: string, originalKey: string, targetKey: string) {
   return chord
     .split("/")
diff --git a/typedoc.json b/typedoc.json
@@ -0,0 +1,11 @@
+{
+  "plugin": ["typedoc-plugin-markdown", "typedoc-vitepress-theme"],
+  "docsRoot": "./docs",
+  "out": "./docs/api",
+  "sidebar": {
+    "autoConfiguration": true,
+    "format": "vitepress",
+    "pretty": false,
+    "collapsed": true
+  }
+}
