Update documentation and improve build setup

Author: ayaka14732

.github/workflows/deploy-docs.yml

@@ -38,7 +38,7 @@ jobs:
     - name: Generate API Documentation
       run: |
         pnpm typedoc
-        sed -i '1s/^/# API Documentation\n\n/' docs/api/index.md
+        ./postprocess_docs.sh
     - run: pnpm docs:build
     - name: Upload artifact
       uses: actions/upload-pages-artifact@v3

README.md

@@ -2,4 +2,45 @@
 
 [![](https://badge.fury.io/js/uinh-kyaengh.svg)](https://www.npmjs.com/package/uinh-kyaengh) [![](https://data.jsdelivr.com/v1/package/npm/uinh-kyaengh/badge)](https://www.jsdelivr.com/package/npm/uinh-kyaengh) [![](https://github.com/nk2028/uinh-kyaengh-js/workflows/Publish/badge.svg)](https://github.com/nk2028/uinh-kyaengh-js/actions?query=workflow%3A%22Publish%22)
 
-A JavaScript library for the _Yunjing_ (韻鏡) system
+UinhKyaengh.js is a JavaScript library for working with 韻鏡系韻圖, specifically 韻鏡 and 七音略. It provides a formalised, programmatic representation of traditional rime tables and enables bidirectional conversion between 韻鏡位置 and [TshetUinh.js](https://github.com/nk2028/tshet-uinh-js) 音韻地位.
+
+The core abstraction of this library is the 韻鏡位置 object. A 韻鏡位置 is defined by a three-dimensional coordinate system consisting of 轉號, 上位, and 右位. From this representation, the library can generate canonical descriptions, perform structural analysis, and interoperate with the 音韻地位 model used in TshetUinh.js.
+
+This library is designed for researchers, developers, and students who require a precise model of traditional Chinese rime tables.
+
+## Installation
+
+```sh
+npm install uinh-kyaengh
+```
+
+## Basic Usage
+
+### Creating a 韻鏡位置
+
+A 韻鏡位置 can be instantiated directly from its coordinates (轉號, 上位, 右位). The object exposes a human-readable description that follows the traditional terminology of 韻鏡.
+
+```javascript
+const 當前韻鏡位置 = new 韻鏡位置(42, 15, 7); // 「直」
+console.log(當前韻鏡位置.描述); // 外轉第四十二圖·舌音第三位·入聲位·韻鏡三等
+```
+
+### Converting 音韻地位 to 韻鏡位置
+
+UinhKyaengh.js supports conversion from TshetUinh.js 音韻地位 objects into 韻鏡位置. This allows existing phonological analyses based on TshetUinh.js to be projected directly onto the 韻鏡 framework.
+
+```javascript
+const 當前音韻地位 = 音韻地位.from描述('澄開三蒸入'); // 「直」
+const 當前韻鏡位置 = 音韻地位2韻鏡位置(當前音韻地位);
+console.log(當前韻鏡位置.坐標); // (42,15,7)
+```
+
+### Converting 韻鏡位置 to 音韻地位
+
+A 韻鏡位置 object can also be converted back into a TshetUinh.js 音韻地位. This makes the mapping between the two systems reversible within the supported domain.
+
+```javascript
+const 當前韻鏡位置 = new 韻鏡位置(42, 15, 7); // 「直」
+const 當前音韻地位 = 當前韻鏡位置.to音韻地位();
+console.log(當前音韻地位.描述); // 澄開三蒸入
+```

docs/.vitepress/config.ts

@@ -9,17 +9,17 @@ export default defineConfig({
   themeConfig: {
     nav: [
       { text: 'Home', link: '/' },
-      { text: 'Introduction', link: '/guide/introduction' },
-      { text: 'API Documentation', link: '/api/' },
+      { text: 'Introduction', link: '/api/' },
+      { text: 'API Documentation', link: '/api/globals' },
     ],
 
     sidebar: {
       '/': [
         {
           text: 'Get Started',
           items: [
-            { text: 'Introduction', link: '/guide/introduction' },
-            { text: 'API Documentation', link: '/api/' },
+            { text: 'Introduction', link: '/api/' },
+            { text: 'API Documentation', link: '/api/globals' },
           ],
         },
       ],

docs/guide/introduction.md

@@ -5,12 +5,12 @@ hero:
   name: UinhKyaengh.js
   tagline: A JavaScript library for the <i>Yunjing</i> (韻鏡) system
   actions:
-    - theme: brand
-      text: Get Started
-      link: /guide/introduction
-    - theme: alt
-      text: View on GitHub
-      link: https://github.com/nk2028/uinh-kyaengh-js
+  - theme: brand
+    text: Get Started
+    link: /api/
+  - theme: alt
+    text: View on GitHub
+    link: https://github.com/nk2028/uinh-kyaengh-js
 
 # features:
 #   - title: 特性一
@@ -19,4 +19,4 @@ hero:
 #     details: 描述
 #   - title: 特性三
 #     details: 描述
----
+---

docs/index.md

@@ -0,0 +1,3 @@
+#!/bin/bash
+sed -i '2{N; /\n\[!\[\](.*)$/d; P; D; }' docs/api/index.md  # Remove badge line
+sed -i '1s/^# uinh-kyaengh$/# API Documentation/' docs/api/globals.md  # Rename title

postprocess_docs.sh

@@ -26,19 +26,19 @@ export const 鈍音母 = [...'幫滂並明見溪羣疑影曉匣云'] as const;
  * - 右位：在一個轉中，從右向左數的位置（1–23）。
  */
 class 韻鏡位置 {
-  /** 轉的序號（1–43） */
+  /** 轉的序號（1–43）。 */
   轉號: number;
 
-  /** 在一個轉中，從上向下數的位置（1–16） */
+  /** 在一個轉中，從上向下數的位置（1–16）。 */
   上位: number;
 
-  /** 在一個轉中，從右向左數的位置（1–23） */
+  /** 在一個轉中，從右向左數的位置（1–23）。 */
   右位: number;
 
   /**
    * 建立一個韻鏡位置。
    *
-   * @throws 若任何座標超出韻鏡合法範圍
+   * @throws 若任何取值超出韻鏡範圍
    */
   constructor(轉號: number, 上位: number, 右位: number) {
     if (轉號 < 1 || 轉號 > 43) {
@@ -64,7 +64,7 @@ class 韻鏡位置 {
   }
 
   /**
-   * 坐標字串表示（如「(1,1,1)」）。
+   * 坐標的字串表示（如「(1,1,1)」）。
   */
   @cached
   get 坐標() {

src/core/韻鏡位置.ts

@@ -6,9 +6,6 @@
   "entryFileName": "index.md",
   "hidePageHeader": true,
   "hideBreadcrumbs": true,
-  "hidePageTitle": true,
-  "useCodeBlocks": true,
-  "readme": "none",
-  "excludePrivate": true,
-  "excludeInternal": true
+  "hidePageTitle": false,
+  "useCodeBlocks": true
 }