docs: automatics better type declarations.

.github/workflows/static.yml

@@ -38,6 +38,7 @@ jobs:
           cache: pnpm
 
       - run: pnpm install
+      - run: pnpm build:types
       - run: pnpm docs:build
 
       - name: Upload artifact

package.json

@@ -61,6 +61,7 @@
   "devDependencies": {
     "@antfu/eslint-config": "^2.16.1",
     "@tsconfig/node20": "^20.1.4",
+    "@types/fs-extra": "^11.0.4",
     "@types/node": "^20.12.8",
     "@unocss/reset": "^0.59.4",
     "@unocss/transformer-directives": "^0.59.4",
@@ -71,9 +72,12 @@
     "cesium": "^1.117.0",
     "consola": "^3.2.3",
     "eslint": "^8.57.0",
+    "fs-extra": "^11.2.0",
     "jsdom": "^24.0.0",
     "markdown-it-mathjax3": "^4.3.2",
     "npm-run-all2": "^6.1.2",
+    "pathe": "^1.1.2",
+    "prettier": "^3.2.5",
     "typescript": "^5.4.5",
     "unocss": "^0.59.4",
     "unplugin-auto-import": "^0.17.5",

src/.vitepress/plugins/markdownTransform.ts

@@ -0,0 +1,66 @@
+import { fileURLToPath } from 'node:url'
+import fs from 'fs-extra'
+import { resolve } from 'pathe'
+import type { Plugin } from 'vite'
+
+import { getTypeDeclaration } from '../utils'
+
+export function markdownTransform(): Plugin {
+  const DIR_CORE = resolve(fileURLToPath(import.meta.url), '../../../core')
+  const DIR_TYPES = resolve(fileURLToPath(import.meta.url), '../../../tsc-types/src/core')
+  const hasTypes = fs.existsSync(DIR_TYPES)
+
+  if (!hasTypes)
+    console.warn('No types dist found, run `pnpm build:types` first.')
+
+  return {
+    name: 'docs-md-transform',
+    enforce: 'pre',
+    async transform(code, id) {
+      if (!id.match(/\.md\b/))
+        return
+
+      const [pkg, name, i] = id.split('/').slice(-3)
+      const lang = langMap(i.split('-')[1].replace(/\.md$/, '') ?? 'en')
+
+      const types = await getTypeDeclaration(pkg, name)
+
+      const URL = 'https://github.com/s3xysteak/cesium-use/blob/main/src/core'
+
+      const existDemo = fs.existsSync(`${DIR_CORE}/${pkg}/${name}/demo.vue`)
+
+      const existsIndex = fs.existsSync(`${DIR_CORE}/${pkg}/${name}/index.ts`)
+
+      return `${code}
+${types
+? `
+## ${lang?.type}
+
+::: details
+
+\`\`\`ts
+${types}
+\`\`\`
+
+:::
+`
+: ''}
+## ${lang?.source}
+
+[source](${`${URL}/${pkg}/${name}/index.${existsIndex ? 'ts' : 'vue'}`})${existDemo ? ` • [demo](${`${URL}/core/${pkg}/${name}/demo.vue`})` : ''}`
+    },
+  }
+}
+
+function langMap(lang: string) {
+  return {
+    en: {
+      type: 'Type Declarations',
+      source: 'Source',
+    },
+    zh: {
+      type: '类型声明',
+      source: '源码',
+    },
+  }[lang]
+}

src/.vitepress/shared.ts

@@ -1,4 +1,5 @@
 import { defineConfig } from 'vitepress'
+import { markdownTransform } from './plugins/markdownTransform'
 
 export const shared = defineConfig({
   title: 'Cesium Use',
@@ -8,12 +9,15 @@ export const shared = defineConfig({
     'core/:part/:module/index.md': ':part/:module.md',
     'core/:part/:module/index-zh.md': 'zh/:part/:module.md',
   },
-  vite: {
-    publicDir: 'docs/public',
-  },
   base: '/cesium-use/',
   head: [['link', { rel: 'icon', href: '/cesium-use/logo.webp' }]],
   markdown: {
     math: true,
   },
+  vite: {
+    publicDir: 'docs/public',
+    plugins: [
+      markdownTransform(),
+    ],
+  },
 })

src/.vitepress/utils.ts

@@ -0,0 +1,35 @@
+import { fileURLToPath } from 'node:url'
+import fs from 'fs-extra'
+import { join, resolve } from 'pathe'
+
+const DIR_TYPES = resolve(fileURLToPath(import.meta.url), '../../../tsc-types/src/core')
+
+export async function getTypeDeclaration(pkg: string, name: string): Promise<string | undefined> {
+  const typingFilepath = join(DIR_TYPES, `${pkg}/${name}/index.d.ts`)
+
+  if (!fs.existsSync(typingFilepath))
+    return
+
+  let types = await fs.readFile(typingFilepath, 'utf-8')
+
+  if (!types)
+    return
+
+  // clean up types
+  types = types
+    .replace('/// <reference types="cesium/Source/Cesium.js" />', '')
+    .replace(/import\(.*?\)\./g, '')
+    .replace(/import[\s\S]+?from ?["'][\s\S]+?["']/g, '')
+    .replace(/export {}/g, '')
+
+  const prettier = await import('prettier')
+  return (await prettier
+    .format(
+      types,
+      {
+        semi: false,
+        parser: 'typescript',
+      },
+    ))
+    .trim()
+}

src/core/composables/useEntityCollection/index-zh.md

@@ -15,21 +15,3 @@ collection.add({
 ```
 
 `useEntityCollection` 会在内部通过`getViewer`获取 viewer 实例。
-
-## 类型声明
-
-::: details
-
-```ts
-// 与Cesium.EntityCollection的使用完全相同，只是重写了增删改查方法
-
-export function useEntityCollection(...args: ConstructorParameters<typeof Cesium.EntityCollection>) {
-  return new EntityCollection(...args)
-}
-
-class EntityCollection extends Cesium.EntityCollection {
-  // ...
-}
-```
-
-:::

src/core/composables/useEntityCollection/index.md

@@ -15,21 +15,3 @@ collection.add({
 ```
 
 The `useEntityCollection` will internally retrieve the viewer instance through `getViewer`.
-
-## Usage Declaration
-
-::: details
-
-```ts
-// It functions identically to Cesium's EntityCollection, with the exception of overridden methods for adding, removing, updating, and querying entities.
-
-export function useEntityCollection(...args: ConstructorParameters<typeof Cesium.EntityCollection>) {
-  return new EntityCollection(...args)
-}
-
-class EntityCollection extends Cesium.EntityCollection {
-  // ...
-}
-```
-
-:::