📝 优化文档显示

.github/workflows/deploy-docs.yml

@@ -40,7 +40,7 @@ jobs:
       - name: Setup API markdown
         run: |-
           python -m pip install litedoc
-          python -m litedoc mbcp -o docs/api -l zh-Hans
+          python -m litedoc mbcp -o docs/zh/api -l zh-Hans
           python -m litedoc mbcp -o docs/en/api -l en
           python -m litedoc mbcp -o docs/ja/api -l ja
           python -m litedoc mbcp -o docs/zht/api -l zh-Hant

.gitignore

@@ -15,7 +15,7 @@ docs/.vitepress/cache
 
 litedoc/
 
-docs/api/
+docs/zh/api/
 docs/zht/api/
 docs/en/api/
 docs/ja/api/

README.md

@@ -12,5 +12,6 @@ A Minecraft particle production library
 
 - [【特效红石音乐】使一颗心免于哀伤 If I Can Stop One Heart From Breaking「崩坏：星穹铁道 EP」](https://www.bilibili.com/video/BV1B1421t7i3)
 
-- AA
+## 其他
-    - BB
+
+- 文档由vitepress强力驱动，API文档由[litedoc](https://github.com/LiteyukiStudio/litedoc)生成

docs/.vitepress/config/common.ts

@@ -1,28 +1,62 @@
 import {defineConfig} from 'vitepress'
+import {generateSidebar} from 'vitepress-sidebar';
+import {zh} from "./zh";
+import {en} from "./en";
+import {ja} from "./ja";
+import {zht} from "./zht";
 
-import AutoSidebarPlugin from 'vitepress-auto-sidebar-plugin'
+let defaultLocale = 'zh';
-
+const commonSidebarOptions = {
+    collapsed: true,
+    convertSameNameSubFileToGroupIndexPage: true,
+    useFolderTitleFromIndexFile: true,
+    useFolderLinkFromIndexFile: true,
+    useTitleFromFrontmatter: true,
+    useTitleFromFileHeading: true,
+    includeFolderIndexFile: true,
+}
 export const common = defineConfig({
     title: "MBCP docs",
     description: "MBCP library docs",
+    markdown: {
+        math: true
+    },
     vite: {
-        plugins: [
+        plugins: [],
-            AutoSidebarPlugin({
+    },
-                // 如果不指定 `srcDir`，则默认使用 `vitepress` 的 `srcDir`
+    rewrites: {
-                ignoreList: [
+        [`${defaultLocale}/:rest*`]: ":rest*",
-                    'README.md'
-                ],
-                title: {
-                    mode: text => text.toLowerCase()
-                }
-            }),
-        ],
     },
     themeConfig: {
-        // https://vitepress.dev/reference/default-theme-config
+        sidebar: generateSidebar(
+            [
+                ...[defaultLocale, 'en', 'ja', 'zht'].map((locale) => {
+                    if (locale === defaultLocale) {
+                        return {
+                            basePath: '/api/',
+                            scanStartPath: `${locale}/api`,
+                            resolvePath: '/api/',
+                            ...commonSidebarOptions
+                        }
+                    } else {
+                        return {
+                            basePath: `/${locale}/api/`,
+                            scanStartPath: `${locale}/api`,
+                            resolvePath: `/${locale}/api/`,
+                            ...commonSidebarOptions
+                        }
+                    }
+                })
+            ]
+        ),
         socialLinks: [
             {icon: 'github', link: 'https://github.com/snowykami/mbcp'}
-        ]
+        ],
+    },
+    locales: {
+        root: {label: "简体中文", ...zh},
+        en: {label: "English", ...en},
+        ja: {label: "日本語", ...ja},
+        zht: {label: "繁體中文", ...zht},
     },
-    srcDir: '.'
 })

docs/.vitepress/config/en.ts

@@ -1,14 +1,17 @@
 import {defineConfig} from 'vitepress'
 
 export const en = defineConfig({
-
     lang: "en-US",
     description: "A library made for Minecraft particle generation",
     themeConfig: {
         nav: [
-            {text: 'Get Start', link: '/guide'},
+            {text: 'Get Start', link: '/en/guide/'},
-            {text: 'API Document', link: '/api/'},
+            {text: 'API Document', link: '/en/api/'},
-            {text: 'Demo', link: '/demo/'},
+            {text: 'Demo', link: '/en/demo/'},
         ],
+        footer: {
+            message: 'Documentation built with <a href="https://vitepress.dev/">VitePress</a> | API references generated by <a href="https://github.com/LiteyukiStudio/litedoc">litedoc</a>',
+            copyright: 'Copyright (C) 2020-2024 SnowyKami. All Rights Reserved'
+        }
     },
 })

docs/.vitepress/config/index.ts

@@ -1,19 +1,6 @@
 import {defineConfig} from "vitepress";
 
 import {common} from './common'
-import {en} from './en'
-import {zh} from './zh'
-import {zht} from './zht'
-import {ja} from './ja'
-
-
-
 export default defineConfig({
     ...common,
-    locales:{
-        root: { label: "简体中文", ...zh },
-        en: { label: "English", ...en },
-        ja: { label: "日本語", ...ja },
-        zht: { label: "繁體中文", ...zht },
-    }
 })

docs/.vitepress/config/ja.ts

@@ -1,14 +1,17 @@
 import {defineConfig} from 'vitepress'
 
 export const ja = defineConfig({
-
     lang: "ja-JP",
     description: "Minecraftのパーティクル生成用のライブラリ",
     themeConfig: {
         nav: [
-            {text: 'スタート', link: '/guide'},
+            {text: 'スタート', link: '/ja/guide/'},
-            {text: 'APIドキュメント', link: '/api/'},
+            {text: 'APIドキュメント', link: '/ja/api/'},
-            {text: 'インスタンス', link: '/demo/'},
+            {text: 'インスタンス', link: '/ja/demo/'},
         ],
+        footer: {
+            message: '<a href="https://vitepress.dev/">VitePress</a> で構築されたドキュメント | <a href="https://github.com/LiteyukiStudio/litedoc">litedoc</a> によって生成されたAPIリファレンス',
+            copyright: 'Copyright (C) 2020-2024 SnowyKami. All Rights Reserved'
+        }
     },
 })

docs/.vitepress/config/zh.ts

@@ -1,7 +1,6 @@
 import {defineConfig} from 'vitepress'
 
 export const zh = defineConfig({
-
     lang: "zh-Hans",
     description: "一个用于Minecraft粒子计算和生成的库",
     themeConfig: {
@@ -10,5 +9,9 @@ export const zh = defineConfig({
             {text: 'API文档', link: '/api/'},
             {text: '实例', link: '/demo/'},
         ],
+        footer: {
+            message: '文档由 <a href="https://vitepress.dev/">VitePress</a> 构建 | API引用由 <a href="https://github.com/LiteyukiStudio/litedoc">litedoc</a> 生成',
+            copyright: 'Copyright (C) 2020-2024 SnowyKami. All Rights Reserved'
+        }
     },
 })

docs/.vitepress/config/zht.ts

@@ -6,9 +6,13 @@ export const zht = defineConfig({
     description: "一個用於Minecraft粒子計算和生成的軟體庫",
     themeConfig: {
         nav: [
-            {text: '指引', link: '/guide/'},
+            {text: '指引', link: '/zht/guide/'},
-            {text: 'API文檔', link: '/api/'},
+            {text: 'API文檔', link: '/zht/api/'},
-            {text: '示範', link: '/demo/'},
+            {text: '示範', link: '/zht/demo/'},
         ],
+        footer: {
+            message: '文檔由 <a href="https://vitepress.dev/">VitePress</a> 構建 | API引用由 <a href="https://github.com/LiteyukiStudio/litedoc">litedoc</a> 生成',
+            copyright: 'Copyright (C) 2020-2024 SnowyKami. All Rights Reserved'
+        }
     },
 })

docs/api-ex.md

@@ -1,49 +0,0 @@
----
-outline: deep
----
-
-# Runtime API Examples
-
-This page demonstrates usage of some of the runtime APIs provided by VitePress.
-
-The main `useData()` API can be used to access site, theme, and page data for the current page. It works in both `.md` and `.vue` files:
-
-```md
-<script setup>
-import { useData } from 'vitepress'
-
-const { theme, page, frontmatter } = useData()
-</script>
-
-## Results
-
-### Theme Data
-<pre>{{ theme }}</pre>
-
-### Page Data
-<pre>{{ page }}</pre>
-
-### Page Frontmatter
-<pre>{{ frontmatter }}</pre>
-```
-
-<script setup>
-import { useData } from 'vitepress'
-
-const { site, theme, page, frontmatter } = useData()
-</script>
-
-## Results
-
-### Theme Data
-<pre>{{ theme }}</pre>
-
-### Page Data
-<pre>{{ page }}</pre>
-
-### Page Frontmatter
-<pre>{{ frontmatter }}</pre>
-
-## More
-
-Check out the documentation for the [full list of runtime APIs](https://vitepress.dev/reference/runtime-api#usedata).

docs/en/guide/index.md

@@ -0,0 +1,3 @@
+# 开始不了一点
+
+$\int_{1}^{2} x111$

docs/en/index.md

@@ -0,0 +1,24 @@
+---
+# https://vitepress.dev/reference/default-theme-home-page
+layout: home
+
+hero:
+  name: "MBCP docs"
+  text: "More basic change particle"
+  tagline: A Library for Python to create particle effects and geometric figures
+  actions:
+    - theme: brand
+      text: Get Started
+      link: ./guide/
+    - theme: alt
+      text: API Reference
+      link: ./api/
+
+features:
+  - title: Easy to use
+    details: Through a simple interface, most of the geometric operations and particle production requirements have been achieved
+  - title: Integrated
+    details: Encapsulated and integrated<code>numpy</code>, <code>scipy</code> and <code>sympy</code>, making script writing as simple as using Geogebra
+  - title: Rich presets
+    details: Rich presets and examples, you can use it directly, and you can also customize the parameters to create your own effects
+---

docs/guide/index.md

@@ -1 +0,0 @@
-# 开始不了一点

docs/ja/guide/index.md

@@ -0,0 +1,3 @@
+# 开始不了一点
+
+$\int_{1}^{2} x111$

docs/ja/index.md

@@ -0,0 +1,24 @@
+---
+# https://vitepress.dev/reference/default-theme-home-page
+layout: home
+
+hero:
+  name: "MBCP docs"
+  text: "More basic change particle"
+  tagline: ジオメトリ演算とパーティクル作成のためのライブラリ
+  actions:
+    - theme: brand
+      text: はじめる
+      link: ./guide/
+    - theme: alt
+      text: API リファレンス
+      link: ./api/
+
+features:
+    - title: 高可用性
+      details: シンプルなインターフェースを通じて、ほとんどのジオメトリ演算とパーティクル作成のニーズを実現しました
+    - title: 高集積度
+      details: <code>numpy</code>、<code>scipy</code>、および<code>sympy</code>をラップして統合し、Geogebraを使用するように簡単にスクリプトを作成できます
+    - title: 組み込みプリセット
+      details: 多くのプリセットを提供しており、一般的なジオメトリ図形やパーティクル効果など、迅速に作成できます
+---

docs/md-ex.md

@@ -1,85 +0,0 @@
-# Markdown Extension Examples
-
-This page demonstrates some of the built-in markdown extensions provided by VitePress.
-
-## Syntax Highlighting
-
-VitePress provides Syntax Highlighting powered by [Shiki](https://github.com/shikijs/shiki), with additional features like line-highlighting:
-
-**Input**
-
-````md
-```js{4}
-export default {
-  data () {
-    return {
-      msg: 'Highlighted!'
-    }
-  }
-}
-```
-````
-
-**Output**
-
-```js{4}
-export default {
-  data () {
-    return {
-      msg: 'Highlighted!'
-    }
-  }
-}
-```
-
-## Custom Containers
-
-**Input**
-
-```md
-::: info
-This is an info box.
-:::
-
-::: tip
-This is a tip.
-:::
-
-::: warning
-This is a warning.
-:::
-
-::: danger
-This is a dangerous warning.
-:::
-
-::: details
-This is a details block.
-:::
-```
-
-**Output**
-
-::: info
-This is an info box.
-:::
-
-::: tip
-This is a tip.
-:::
-
-::: warning
-This is a warning.
-:::
-
-::: danger
-This is a dangerous warning.
-:::
-
-::: details
-This is a details block.
-:::
-
-## More
-
-Check out the documentation for the [full list of markdown extensions](https://vitepress.dev/guide/markdown).

docs/package.json

@@ -1,12 +1,16 @@
 {
   "devDependencies": {
     "vitepress": "^1.3.4",
-    "vitepress-auto-sidebar-plugin": "^0.2.4"
+    "vitepress-auto-sidebar-plugin": "^0.2.4",
+    "vitepress-sidebar": "^1.25.0"
   },
   "scripts": {
     "docs:dev": "vitepress dev",
     "docs:build": "vitepress build",
     "docs:preview": "vitepress preview"
   },
-  "type": "module"
+  "type": "module",
+  "dependencies": {
+    "markdown-it-mathjax3": "^4.3.2"
+  }
 }

docs/pnpm-lock.yaml

@@ -4,13 +4,21 @@ settings:
   autoInstallPeers: true
   excludeLinksFromLockfile: false
 
+dependencies:
+  markdown-it-mathjax3:
+    specifier: ^4.3.2
+    version: 4.3.2
+
 devDependencies:
   vitepress:
     specifier: ^1.3.4
-    version: 1.3.4(@algolia/client-search@5.1.1)(search-insights@2.17.0)
+    version: 1.3.4(@algolia/client-search@5.1.1)(markdown-it-mathjax3@4.3.2)(search-insights@2.17.0)
   vitepress-auto-sidebar-plugin:
     specifier: ^0.2.4
     version: 0.2.4(vite@5.4.2)(vitepress@1.3.4)
+  vitepress-sidebar:
+    specifier: ^1.25.0
+    version: 1.25.0
 
 packages:
 
@@ -880,6 +888,10 @@ packages:
       '@algolia/transporter': 4.24.0
     dev: true
 
+  /ansi-colors@4.1.3:
+    resolution: {integrity: sha512-/6w/C21Pm1A7aZitlI5Ni/2J6FFQN8i1Cvz3kHABAAbw93v/NlvKdVOqz7CCWz/3iv/JplRSEEZ83XION15ovw==}
+    engines: {node: '>=6'}
+
   /argparse@1.0.10:
     resolution: {integrity: sha512-o5Roy6tNG4SL/FOkCAN6RzjiakZS25RLYFrcMttJqbdd8BWrnA+fGz57iN5Pb06pvBGvl5gQ0B48dJlslXvoTg==}
     dependencies:
@@ -890,6 +902,9 @@ packages:
     resolution: {integrity: sha512-+hkTxhot+dWsLpp3gia5AkVHIsKlZybNT5gIYiDlNzJrmYPcTM9k5/w2uaj3IPpd7LlEYpmCj4Jj1nC41VhDFg==}
     dev: true
 
+  /boolbase@1.0.0:
+    resolution: {integrity: sha512-JZOSA7Mo9sNGB8+UjSgzdLtokWAky1zbztM3WRLCbZ70/3cTANmQmOdR7y2g+J0e2WXywy1yS468tY+IruqEww==}
+
   /braces@3.0.3:
     resolution: {integrity: sha512-yQbXgO/OSZVD2IsiLlro+7Hf6Q18EJrKSEsdoMzKePKXct3gvD8oLcOQdIzGupr5Fj+EDe8gO/lxc1BzfMpxvA==}
     engines: {node: '>=8'}
@@ -897,6 +912,35 @@ packages:
       fill-range: 7.1.1
     dev: true
 
+  /cheerio-select@1.6.0:
+    resolution: {integrity: sha512-eq0GdBvxVFbqWgmCm7M3XGs1I8oLy/nExUnh6oLqmBditPO9AqQJrkslDpMun/hZ0yyTs8L0m85OHp4ho6Qm9g==}
+    dependencies:
+      css-select: 4.3.0
+      css-what: 6.1.0
+      domelementtype: 2.3.0
+      domhandler: 4.3.1
+      domutils: 2.8.0
+
+  /cheerio@1.0.0-rc.10:
+    resolution: {integrity: sha512-g0J0q/O6mW8z5zxQ3A8E8J1hUgp4SMOvEoW/x84OwyHKe/Zccz83PVT4y5Crcr530FV6NgmKI1qvGTKVl9XXVw==}
+    engines: {node: '>= 6'}
+    dependencies:
+      cheerio-select: 1.6.0
+      dom-serializer: 1.4.1
+      domhandler: 4.3.1
+      htmlparser2: 6.1.0
+      parse5: 6.0.1
+      parse5-htmlparser2-tree-adapter: 6.0.1
+      tslib: 2.7.0
+
+  /commander@6.2.1:
+    resolution: {integrity: sha512-U7VdrJFnJgo4xjrHpTzu0yrHPGImdsmD95ZlgYSEajAn2JKzDhDTPG9kBTefmObL2w/ngeZnilk+OV9CG3d7UA==}
+    engines: {node: '>= 6'}
+
+  /commander@9.2.0:
+    resolution: {integrity: sha512-e2i4wANQiSXgnrBlIatyHtP1odfUp0BbV5Y5nEGbxtIrStkEOAAzCUirvLBNXHLr7kwLvJl6V+4V3XV9x7Wd9w==}
+    engines: {node: ^12.20.0 || >=14}
+
   /consola@3.2.3:
     resolution: {integrity: sha512-I5qxpzLv+sJhTVEoLYNcTW+bThDCPsit0vLNKShZx6rLtpilNpmmeTPaeqJb9ZE9dV3DGaeby6Vuhrw38WjeyQ==}
     engines: {node: ^14.18.0 || >=16.10.0}
@@ -909,10 +953,55 @@ packages:
       is-what: 4.1.16
     dev: true
 
+  /css-select@4.3.0:
+    resolution: {integrity: sha512-wPpOYtnsVontu2mODhA19JrqWxNsfdatRKd64kmpRbQgh1KtItko5sTnEpPdpSaJszTOhEMlF/RPz28qj4HqhQ==}
+    dependencies:
+      boolbase: 1.0.0
+      css-what: 6.1.0
+      domhandler: 4.3.1
+      domutils: 2.8.0
+      nth-check: 2.1.1
+
+  /css-what@6.1.0:
+    resolution: {integrity: sha512-HTUrgRJ7r4dsZKU6GjmpfRK1O76h97Z8MfS1G0FozR+oF2kG6Vfe8JE6zwrkbxigziPHinCJ+gCPjA9EaBDtRw==}
+    engines: {node: '>= 6'}
+
   /csstype@3.1.3:
     resolution: {integrity: sha512-M1uQkMl8rQK/szD0LNhtqxIPLpimGm8sOBwU7lLnCpSbTyY3yeU1Vc7l4KT5zT4s/yOxHH5O7tIuuLOCnLADRw==}
     dev: true
 
+  /dom-serializer@1.4.1:
+    resolution: {integrity: sha512-VHwB3KfrcOOkelEG2ZOfxqLZdfkil8PtJi4P8N2MMXucZq2yLp75ClViUlOVwyoHEDjYU433Aq+5zWP61+RGag==}
+    dependencies:
+      domelementtype: 2.3.0
+      domhandler: 4.3.1
+      entities: 2.2.0
+
+  /domelementtype@2.3.0:
+    resolution: {integrity: sha512-OLETBj6w0OsagBwdXnPdN0cnMfF9opN69co+7ZrbfPGrdpPVNBUj02spi6B1N7wChLQiPn4CSH/zJvXw56gmHw==}
+
+  /domhandler@3.3.0:
+    resolution: {integrity: sha512-J1C5rIANUbuYK+FuFL98650rihynUOEzRLxW+90bKZRWB6A1X1Tf82GxR1qAWLyfNPRvjqfip3Q5tdYlmAa9lA==}
+    engines: {node: '>= 4'}
+    dependencies:
+      domelementtype: 2.3.0
+
+  /domhandler@4.3.1:
+    resolution: {integrity: sha512-GrwoxYN+uWlzO8uhUXRl0P+kHE4GtVPfYzVLcUxPL7KNdHKj66vvlhiweIHqYYXWlw+T8iLMp42Lm67ghw4WMQ==}
+    engines: {node: '>= 4'}
+    dependencies:
+      domelementtype: 2.3.0
+
+  /domutils@2.8.0:
+    resolution: {integrity: sha512-w96Cjofp72M5IIhpjgobBimYEfoPjx1Vx0BSX9P30WBdZW2WIKU0T1Bd0kz2eNZ9ikjKgHbEyKx8BB6H1L3h3A==}
+    dependencies:
+      dom-serializer: 1.4.1
+      domelementtype: 2.3.0
+      domhandler: 4.3.1
+
+  /entities@2.2.0:
+    resolution: {integrity: sha512-p92if5Nz619I0w+akJrLZH0MX0Pb5DX39XOwQTtXSdQQOaYH03S1uIQp4mhOZtAXrxq4ViO67YTiLBo2638o9A==}
+
   /entities@4.5.0:
     resolution: {integrity: sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw==}
     engines: {node: '>=0.12'}
@@ -949,6 +1038,14 @@ packages:
       '@esbuild/win32-x64': 0.21.5
     dev: true
 
+  /escape-goat@3.0.0:
+    resolution: {integrity: sha512-w3PwNZJwRxlp47QGzhuEBldEqVHHhh8/tIPcl6ecf2Bou99cdAt0knihBV0Ecc7CGxYduXVBDheH1K2oADRlvw==}
+    engines: {node: '>=10'}
+
+  /esm@3.2.25:
+    resolution: {integrity: sha512-U1suiZ2oDVWv4zPO56S0NcR5QriEahGtdN2OR6FiOG4WJvcjBVFB0qI4+eKoWFH483PKGuLuu6V8Z4T5g63UVA==}
+    engines: {node: '>=6'}
+
   /esprima@4.0.1:
     resolution: {integrity: sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A==}
     engines: {node: '>=4'}
@@ -1025,6 +1122,22 @@ packages:
     resolution: {integrity: sha512-Yc+BQe8SvoXH1643Qez1zqLRmbA5rCL+sSmk6TVos0LWVfNIB7PGncdlId77WzLGSIB5KaWgTaNTs2lNVEI6VQ==}
     dev: true
 
+  /htmlparser2@5.0.1:
+    resolution: {integrity: sha512-vKZZra6CSe9qsJzh0BjBGXo8dvzNsq/oGvsjfRdOrrryfeD9UOBEEQdeoqCRmKZchF5h2zOBMQ6YuQ0uRUmdbQ==}
+    dependencies:
+      domelementtype: 2.3.0
+      domhandler: 3.3.0
+      domutils: 2.8.0
+      entities: 2.2.0
+
+  /htmlparser2@6.1.0:
+    resolution: {integrity: sha512-gyyPk6rgonLFEDGoeRgQNaEUvdJ4ktTmmUh/h2t7s+M8oPpIPxgNACWa+6ESR57kXstwqPiCut0V8NRpcwgU7A==}
+    dependencies:
+      domelementtype: 2.3.0
+      domhandler: 4.3.1
+      domutils: 2.8.0
+      entities: 2.2.0
+
   /is-extendable@0.1.1:
     resolution: {integrity: sha512-5BMULNob1vgFX6EjQw5izWDxrecWK9AM72rugNr0TFldMOi0fj6Jk+zeKIt0xGj4cEfQIJth4w3OKWOJ4f+AFw==}
     engines: {node: '>=0.10.0'}
@@ -1060,6 +1173,19 @@ packages:
       esprima: 4.0.1
     dev: true
 
+  /juice@8.1.0:
+    resolution: {integrity: sha512-FLzurJrx5Iv1e7CfBSZH68dC04EEvXvvVvPYB7Vx1WAuhCp1ZPIMtqxc+WTWxVkpTIC2Ach/GAv0rQbtGf6YMA==}
+    engines: {node: '>=10.0.0'}
+    hasBin: true
+    dependencies:
+      cheerio: 1.0.0-rc.10
+      commander: 6.2.1
+      mensch: 0.3.4
+      slick: 1.12.2
+      web-resource-inliner: 6.0.1
+    transitivePeerDependencies:
+      - encoding
+
   /kind-of@6.0.3:
     resolution: {integrity: sha512-dcS1ul+9tmeD95T+x28/ehLgd9mENa3LsvDTtzm3vyBEO7RPptvAD+t44WVXaUjTBRcrpFeFlC8WCruUR456hw==}
     engines: {node: '>=0.10.0'}
@@ -1075,11 +1201,33 @@ packages:
     resolution: {integrity: sha512-1I+1qpDt4idfgLQG+BNWmrqku+7/2bi5nLf4YwF8y8zXvmfiTBY3PV3ZibfrjBueCByROpuBjLLFCajqkgYoLQ==}
     dev: true
 
+  /markdown-it-mathjax3@4.3.2:
+    resolution: {integrity: sha512-TX3GW5NjmupgFtMJGRauioMbbkGsOXAAt1DZ/rzzYmTHqzkO1rNAdiMD4NiruurToPApn2kYy76x02QN26qr2w==}
+    dependencies:
+      juice: 8.1.0
+      mathjax-full: 3.2.2
+    transitivePeerDependencies:
+      - encoding
+
+  /mathjax-full@3.2.2:
+    resolution: {integrity: sha512-+LfG9Fik+OuI8SLwsiR02IVdjcnRCy5MufYLi0C3TdMT56L/pjB0alMVGgoWJF8pN9Rc7FESycZB9BMNWIid5w==}
+    dependencies:
+      esm: 3.2.25
+      mhchemparser: 4.2.1
+      mj-context-menu: 0.6.1
+      speech-rule-engine: 4.0.7
+
+  /mensch@0.3.4:
+    resolution: {integrity: sha512-IAeFvcOnV9V0Yk+bFhYR07O3yNina9ANIN5MoXBKYJ/RLYPurd2d0yw14MDhpr9/momp0WofT1bPUh3hkzdi/g==}
+
   /merge2@1.4.1:
     resolution: {integrity: sha512-8q7VEgMJW4J8tcfVPy8g09NcQwZdbwFEqhe/WZkoIzjn/3TGDwtOCYtXGxA3O8tPzpczCCDgv+P2P5y00ZJOOg==}
     engines: {node: '>= 8'}
     dev: true
 
+  /mhchemparser@4.2.1:
+    resolution: {integrity: sha512-kYmyrCirqJf3zZ9t/0wGgRZ4/ZJw//VwaRVGA75C4nhE60vtnIzhl9J9ndkX/h6hxSN7pjg/cE0VxbnNM+bnDQ==}
+
   /micromatch@4.0.8:
     resolution: {integrity: sha512-PXwfBhYu0hBCPw8Dn0E+WDYb7af3dSLVWKi3HGv84IdF4TyFoC0ysxFd0Goxw7nSv4T/PzEJQxsYsEiFCKo2BA==}
     engines: {node: '>=8.6'}
@@ -1088,6 +1236,11 @@ packages:
       picomatch: 2.3.1
     dev: true
 
+  /mime@2.6.0:
+    resolution: {integrity: sha512-USPkMeET31rOMiarsBNIHZKLGgvKc/LrjofAnBlOttf5ajRvqiRA8QsenbcooctK6d6Ts6aqZXBA+XbkKthiQg==}
+    engines: {node: '>=4.0.0'}
+    hasBin: true
+
   /minisearch@7.1.0:
     resolution: {integrity: sha512-tv7c/uefWdEhcu6hvrfTihflgeEi2tN6VV7HJnCjK6VxM75QQJh4t9FwJCsA2EsRS8LCnu3W87CuGPWMocOLCA==}
     dev: true
@@ -1096,12 +1249,39 @@ packages:
     resolution: {integrity: sha512-vKivATfr97l2/QBCYAkXYDbrIWPM2IIKEl7YPhjCvKlG3kE2gm+uBo6nEXK3M5/Ffh/FLpKExzOQ3JJoJGFKBw==}
     dev: true
 
+  /mj-context-menu@0.6.1:
+    resolution: {integrity: sha512-7NO5s6n10TIV96d4g2uDpG7ZDpIhMh0QNfGdJw/W47JswFcosz457wqz/b5sAKvl12sxINGFCn80NZHKwxQEXA==}
+
   /nanoid@3.3.7:
     resolution: {integrity: sha512-eSRppjcPIatRIMC1U6UngP8XFcz8MQWGQdt1MTBQ7NaAmvXDfvNxbvWV3x2y6CdEUciCSsDHDQZbhYaB8QEo2g==}
     engines: {node: ^10 || ^12 || ^13.7 || ^14 || >=15.0.1}
     hasBin: true
     dev: true
 
+  /node-fetch@2.7.0:
+    resolution: {integrity: sha512-c4FRfUm/dbcWZ7U+1Wq0AwCyFL+3nt2bEw05wfxSz+DWpWsitgmSgYmy2dQdWyKC1694ELPqMs/YzUSNozLt8A==}
+    engines: {node: 4.x || >=6.0.0}
+    peerDependencies:
+      encoding: ^0.1.0
+    peerDependenciesMeta:
+      encoding:
+        optional: true
+    dependencies:
+      whatwg-url: 5.0.0
+
+  /nth-check@2.1.1:
+    resolution: {integrity: sha512-lqjrjmaOoAnWfMmBPL+XNnynZh2+swxiX3WUE0s4yEHI6m+AwrK2UZOimIRl3X/4QctVqS8AiZjFqyOGrMXb/w==}
+    dependencies:
+      boolbase: 1.0.0
+
+  /parse5-htmlparser2-tree-adapter@6.0.1:
+    resolution: {integrity: sha512-qPuWvbLgvDGilKc5BoicRovlT4MtYT6JfJyBOMDsKoiT+GiuP5qyrPCnR9HcPECIJJmZh5jRndyNThnhhb/vlA==}
+    dependencies:
+      parse5: 6.0.1
+
+  /parse5@6.0.1:
+    resolution: {integrity: sha512-Ofn/CTFzRGTTxwpNEs9PP93gXShHcTq255nzRYSKe8AkVpZY7e1fpmTfOyoIvjP5HG7Z2ZM7VS9PPhQGW2pOpw==}
+
   /pathe@1.1.2:
     resolution: {integrity: sha512-whLdWMYL2TwI08hn8/ZqAbrVemu0LNaNNJZX73O6qaIdCTfXutsLhMkjdENX0qhsQ9uIimo4/aQOmXkoon2nDQ==}
     dev: true
@@ -1196,6 +1376,9 @@ packages:
       '@types/hast': 3.0.4
     dev: true
 
+  /slick@1.12.2:
+    resolution: {integrity: sha512-4qdtOGcBjral6YIBCWJ0ljFSKNLz9KkhbWtuGvUyRowl1kxfuE1x/Z/aJcaiilpb3do9bl5K7/1h9XC5wWpY/A==}
+
   /source-map-js@1.2.0:
     resolution: {integrity: sha512-itJW8lvSA0TXEphiRoawsCksnlf8SyvmFzIhltqAHluXd88pkCd+cXJVHTDwdCr0IzwptSm035IHQktUu1QUMg==}
     engines: {node: '>=0.10.0'}
@@ -1206,6 +1389,14 @@ packages:
     engines: {node: '>=0.10.0'}
     dev: true
 
+  /speech-rule-engine@4.0.7:
+    resolution: {integrity: sha512-sJrL3/wHzNwJRLBdf6CjJWIlxC04iYKkyXvYSVsWVOiC2DSkHmxsqOhEeMsBA9XK+CHuNcsdkbFDnoUfAsmp9g==}
+    hasBin: true
+    dependencies:
+      commander: 9.2.0
+      wicked-good-xpath: 1.3.0
+      xmldom-sre: 0.1.31
+
   /sprintf-js@1.0.3:
     resolution: {integrity: sha512-D9cPgkvLlV3t3IzL0D0YLvGA9Ahk4PcvVwUbN0dSGr1aP0Nrt4AEnTUbuGvquEC0mA64Gqt1fzirlRs5ibXx8g==}
     dev: true
@@ -1238,6 +1429,16 @@ packages:
       is-number: 7.0.0
     dev: true
 
+  /tr46@0.0.3:
+    resolution: {integrity: sha512-N3WMsuqV66lT30CrXNbEjx4GEwlow3v6rr4mCcv6prnfwhS01rkgyFdjPNBYd9br7LpXV1+Emh01fHnq2Gdgrw==}
+
+  /tslib@2.7.0:
+    resolution: {integrity: sha512-gLXCKdN1/j47AiHiOkJN69hJmcbGTHI0ImLmbYLHykhgeN0jVGola9yVjFgzCUklsZQMW55o+dW7IXv3RCXDzA==}
+
+  /valid-data-url@3.0.1:
+    resolution: {integrity: sha512-jOWVmzVceKlVVdwjNSenT4PbGghU0SBIizAev8ofZVgivk/TVHXSbNL8LP6M3spZvkR9/QolkyJavGSX5Cs0UA==}
+    engines: {node: '>=10'}
+
   /vite@5.4.2:
     resolution: {integrity: sha512-dDrQTRHp5C1fTFzcSaMxjk6vdpKvT+2/mIdE07Gw2ykehT49O0z/VHS3zZ8iV/Gh8BJJKHWOe5RjaNrW5xf/GA==}
     engines: {node: ^18.0.0 || >=20.0.0}
@@ -1288,10 +1489,17 @@ packages:
       pathe: 1.1.2
       perfect-debounce: 1.0.0
       vite: 5.4.2
-      vitepress: 1.3.4(@algolia/client-search@5.1.1)(search-insights@2.17.0)
+      vitepress: 1.3.4(@algolia/client-search@5.1.1)(markdown-it-mathjax3@4.3.2)(search-insights@2.17.0)
     dev: true
 
-  /vitepress@1.3.4(@algolia/client-search@5.1.1)(search-insights@2.17.0):
+  /vitepress-sidebar@1.25.0:
+    resolution: {integrity: sha512-hbS6DEQjdZS1lbm8p1AKrzdfoFDf4Eas/Dmr1xbN+yv9XVf6xAW+q4tJINmuAt6vnvkEgylZlcH1PGzKX0RgcA==}
+    engines: {node: '>=18.0.0'}
+    dependencies:
+      gray-matter: 4.0.3
+    dev: true
+
+  /vitepress@1.3.4(@algolia/client-search@5.1.1)(markdown-it-mathjax3@4.3.2)(search-insights@2.17.0):
     resolution: {integrity: sha512-I1/F6OW1xl3kW4PaIMC6snxjWgf3qfziq2aqsDoFc/Gt41WbcRv++z8zjw8qGRIJ+I4bUW7ZcKFDHHN/jkH9DQ==}
     hasBin: true
     peerDependencies:
@@ -1315,6 +1523,7 @@ packages:
       '@vueuse/integrations': 11.0.3(focus-trap@7.5.4)(vue@3.4.38)
       focus-trap: 7.5.4
       mark.js: 8.11.1
+      markdown-it-mathjax3: 4.3.2
       minisearch: 7.1.0
       shiki: 1.14.1
       vite: 5.4.2
@@ -1377,3 +1586,32 @@ packages:
       '@vue/server-renderer': 3.4.38(vue@3.4.38)
       '@vue/shared': 3.4.38
     dev: true
+
+  /web-resource-inliner@6.0.1:
+    resolution: {integrity: sha512-kfqDxt5dTB1JhqsCUQVFDj0rmY+4HLwGQIsLPbyrsN9y9WV/1oFDSx3BQ4GfCv9X+jVeQ7rouTqwK53rA/7t8A==}
+    engines: {node: '>=10.0.0'}
+    dependencies:
+      ansi-colors: 4.1.3
+      escape-goat: 3.0.0
+      htmlparser2: 5.0.1
+      mime: 2.6.0
+      node-fetch: 2.7.0
+      valid-data-url: 3.0.1
+    transitivePeerDependencies:
+      - encoding
+
+  /webidl-conversions@3.0.1:
+    resolution: {integrity: sha512-2JAn3z8AR6rjK8Sm8orRC0h/bcl/DqL7tRPdGZ4I1CjdF+EaMLmYxBHyXuKL849eucPFhvBoxMsflfOb8kxaeQ==}
+
+  /whatwg-url@5.0.0:
+    resolution: {integrity: sha512-saE57nupxk6v3HY35+jzBwYa0rKSy0XR8JSxZPwgLr7ys0IBzhGviA1/TUGJLmSVqs8pb9AnvICXEuOHLprYTw==}
+    dependencies:
+      tr46: 0.0.3
+      webidl-conversions: 3.0.1
+
+  /wicked-good-xpath@1.3.0:
+    resolution: {integrity: sha512-Gd9+TUn5nXdwj/hFsPVx5cuHHiF5Bwuc30jZ4+ronF1qHK5O7HD0sgmXWSEgwKquT3ClLoKPVbO6qGwVwLzvAw==}
+
+  /xmldom-sre@0.1.31:
+    resolution: {integrity: sha512-f9s+fUkX04BxQf+7mMWAp5zk61pciie+fFLC9hX9UVvCeJQfNHRHXpeo5MPcR0EUf57PYLdt+ZO4f3Ipk2oZUw==}
+    engines: {node: '>=0.1'}

docs/zh/demo/index.md

@@ -0,0 +1 @@
+# demo

docs/zh/guide/index.md

@@ -0,0 +1,3 @@
+# 开始不了一点
+
+$\int_{1}^{2} x111$

docs/zh/index.md

@@ -9,10 +9,10 @@ hero:
   actions:
     - theme: brand
       text: 快速开始
-      link: guide/
+      link: ./guide/
     - theme: alt
       text: API文档
-      link: api/
+      link: ./api/
 
 features:
   - title: 高可用性

docs/zht/guide/index.md

@@ -0,0 +1,3 @@
+# 开始不了一点
+
+$\int_{1}^{2} x111$

docs/zht/index.md

@@ -0,0 +1,24 @@
+---
+# https://vitepress.dev/reference/default-theme-home-page
+layout: home
+
+hero:
+  name: "MBCP docs"
+  text: "More basic change particle"
+  tagline: 用於幾何運算和粒子製作的軟體庫
+  actions:
+    - theme: brand
+      text: 跟隨引導
+      link: ./guide/
+    - theme: alt
+      text: API文檔
+      link: ./api/
+
+features:
+  - title: 高度易用
+    details: 通過簡單的接口，實現了大部分幾何運算及粒子製作的需求
+  - title: 高度集成
+    details: 對<code>numpy</code>、<code>scipy</code>及<code>sympy</code>進行了封裝和集成，使腳本編寫像使用Geogebra一樣easy
+  - title: 內置預設
+    details: 提供了大量的預設，包括常見的幾何圖形、粒子效果等，便於快速生產
+---

mbcp/__init__.py

@@ -1,11 +1,5 @@
 # -*- coding: utf-8 -*-
 """
-Copyright (C) 2020-2024 LiteyukiStudio. All Rights Reserved 
+本模块塞了一些预设的粒子生成器
-
-@Time    : 2024/8/6 下午12:54
-@Author  : snowykami
-@Email   : snowykami@outlook.com
-@File    : __init__.py
-@Software: PyCharm
 """
 from .mp_math import *

mbcp/mp_math/__init__.py

@@ -1,12 +1,14 @@
 # -*- coding: utf-8 -*-
 """
-Copyright (C) 2020-2024 LiteyukiStudio. All Rights Reserved 
+本包定义了一些常用的导入，可直接从`mbcp.mp_math`导入使用
-
+导入的类有：
-@Time    : 2024/8/6 下午12:57
+- `AnyAngle`：任意角
-@Author  : snowykami
+- `CurveEquation`：曲线方程
-@Email   : snowykami@outlook.com
+- `Line3`：三维直线
-@File    : __init__.py.py
+- `Plane3`：三维平面
-@Software: PyCharm
+- `Point3`：三维点
+- `Segment3`：三维线段
+- `Vector3`：三维向量
 """
 from .angle import AnyAngle
 from .const import *

mbcp/mp_math/angle.py

@@ -1,12 +1,6 @@
 # -*- coding: utf-8 -*-
 """
-Copyright (C) 2020-2024 LiteyukiStudio. All Rights Reserved 
+本模块定义了角度相关的类
-
-@Time    : 2024/8/26 上午6:29
-@Author  : snowykami
-@Email   : snowykami@outlook.com
-@File    : angle.py
-@Software: PyCharm
 """
 import math
 from typing import overload

mbcp/mp_math/const.py

@@ -1,21 +1,19 @@
 # -*- coding: utf-8 -*-
 """
-Copyright (C) 2020-2024 LiteyukiStudio. All Rights Reserved 
+本模块定义了一些常用的常量
-
-@Time    : 2024/8/25 下午9:45
-@Author  : snowykami
-@Email   : snowykami@outlook.com
-@File    : const.py
-@Software: PyCharm
 """
 import math
 
 
 PI = math.pi
+"""常量 π"""
 E = math.e
+"""自然对数的底 exp(1)"""
 GOLDEN_RATIO = (1 + math.sqrt(5)) / 2
+"""黄金分割比"""
 GAMMA = 0.57721566490153286060651209008240243104215933593992
+"""欧拉常数"""
 EPSILON = 0.0001
-"""ε"""
+"""精度误差"""
 APPROX = 0.001
-"""约等于误差"""
+"""约等于判定误差"""

mbcp/mp_math/equation.py

@@ -1,17 +1,11 @@
 # -*- coding: utf-8 -*-
 """
-Copyright (C) 2020-2024 LiteyukiStudio. All Rights Reserved 
+本模块定义了方程相关的类和函数以及一些常用的数学函数
-
-@Time    : 2024/8/9 上午11:32
-@Author  : snowykami
-@Email   : snowykami@outlook.com
-@File    : equation.py
-@Software: PyCharm
 """
 
-from mbcp.mp_math.mp_math_typing import OneVarFunc, Var, MultiVarsFunc, Number
+from .mp_math_typing import OneVarFunc, Var, MultiVarsFunc, Number
-from mbcp.mp_math.point import Point3
+from .point import Point3
-from mbcp.mp_math.const import EPSILON
+from .const import EPSILON
 
 
 class CurveEquation:
@@ -34,7 +28,7 @@ class CurveEquation:
             *t:
                 参数
         Returns:
-
+            目标点
         """
         if len(t) == 1:
             return Point3(self.x_func(t[0]), self.y_func(t[0]), self.z_func(t[0]))
@@ -73,7 +67,14 @@ def get_partial_derivative_func(func: MultiVarsFunc, var: int | tuple[int, ...],
         return partial_derivative_func
     elif isinstance(var, tuple):
         def high_order_partial_derivative_func(*args: Var) -> Var:
-            """@litedoc-hide"""
+            """
+            @litedoc-hide
+            求高阶偏导函数
+            Args:
+                *args: 参数
+            Returns:
+                高阶偏导数值
+            """
             result_func = func
             for v in var:
                 result_func = get_partial_derivative_func(result_func, v, epsilon)

mbcp/mp_math/function.py

@@ -0,0 +1,27 @@
+"""
+AAA
+"""
+
+from .mp_math_typing import ThreeSingleVarsFunc
+from .point import Point3
+from .vector import Vector3
+from .const import EPSILON
+
+
+def cal_gradient_3vf(func: ThreeSingleVarsFunc, p: Point3, epsilon: float = EPSILON) -> Vector3:
+    r"""
+    计算三元函数在某点的梯度向量。
+    > [!tip]
+    > 已知一个函数$f(x, y, z)$，则其在点$(x_0, y_0, z_0)$处的梯度向量为:
+    $\nabla f(x_0, y_0, z_0) = \left(\frac{\partial f}{\partial x}, \frac{\partial f}{\partial y}, \frac{\partial f}{\partial z}\right)$
+    Args:
+        func: 三元函数
+        p: 点
+        epsilon: 偏移量
+    Returns:
+        梯度
+    """
+    dx = (func(p.x + epsilon, p.y, p.z) - func(p.x - epsilon, p.y, p.z)) / (2 * epsilon)
+    dy = (func(p.x, p.y + epsilon, p.z) - func(p.x, p.y - epsilon, p.z)) / (2 * epsilon)
+    dz = (func(p.x, p.y, p.z + epsilon) - func(p.x, p.y, p.z - epsilon)) / (2 * epsilon)
+    return Vector3(dx, dy, dz)

mbcp/mp_math/line.py

@@ -1,12 +1,6 @@
 # -*- coding: utf-8 -*-
 """
-Copyright (C) 2020-2024 LiteyukiStudio. All Rights Reserved 
+本模块定义了三维空间中的直线类
-
-@Time    : 2024/8/6 下午12:57
-@Author  : snowykami
-@Email   : snowykami@outlook.com
-@File    : other.py
-@Software: PyCharm
 """
 import math
 from typing import TYPE_CHECKING

mbcp/mp_math/mp_math_typing.py

@@ -1,12 +1,6 @@
 # -*- coding: utf-8 -*-
 """
-Copyright (C) 2020-2024 LiteyukiStudio. All Rights Reserved 
+本模块用于内部类型提示
-
-@Time    : 2024/8/9 上午11:35
-@Author  : snowykami
-@Email   : snowykami@outlook.com
-@File    : mp_math_typing.py
-@Software: PyCharm
 """
 from typing import Callable, Iterable, TypeAlias, TypeVar
 

mbcp/mp_math/plane.py

@@ -1,17 +1,16 @@
 # -*- coding: utf-8 -*-
 """
-平面模块
+本模块定义了三维空间中的平面类
 """
 import math
 from typing import TYPE_CHECKING, overload
 
 import numpy as np
 
-from .const import APPROX
-from .vector import Vector3, zero_vector3
 from .line import Line3
 from .point import Point3
 from .utils import approx, sign
+from .vector import Vector3, zero_vector3
 
 if TYPE_CHECKING:
     from .angle import AnyAngle

mbcp/mp_math/point.py

@@ -1,3 +1,7 @@
+"""
+本模块定义了三维空间中点的类。
+"""
+
 from typing import TYPE_CHECKING, overload
 
 from .const import APPROX

mbcp/mp_math/segment.py

@@ -1,12 +1,6 @@
 # -*- coding: utf-8 -*-
 """
-Copyright (C) 2020-2024 LiteyukiStudio. All Rights Reserved 
+本模块定义了三维空间中的线段类
-
-@Time    : 2024/8/7 上午12:42
-@Author  : snowykami
-@Email   : snowykami@outlook.com
-@File    : segment.py
-@Software: PyCharm
 """
 
 from typing import TYPE_CHECKING

mbcp/mp_math/utils.py

@@ -1,12 +1,6 @@
 # -*- coding: utf-8 -*-
 """
-Copyright (C) 2020-2024 LiteyukiStudio. All Rights Reserved 
+本模块定义了一些常用的工具函数
-
-@Time    : 2024/8/12 下午9:16
-@Author  : snowykami
-@Email   : snowykami@outlook.com
-@File    : utils.py
-@Software: PyCharm
 """
 from typing import overload, TYPE_CHECKING
 

mbcp/mp_math/vector.py

@@ -1,17 +1,18 @@
+"""
+本模块定义了3维向量的类Vector3，以及一些常用的向量。
+"""
+
 import math
-from typing import overload, TYPE_CHECKING
+from typing import overload
 
 import numpy as np
 
+from .angle import AnyAngle
 from .const import APPROX
 from .mp_math_typing import RealNumber
 from .point import Point3
-from .angle import AnyAngle
 from .utils import approx
 
-# if TYPE_CHECKING:
-#
-
 
 class Vector3:
     def __init__(self, x: float, y: float, z: float):

mbcp/particle/__init__.py

@@ -1,10 +1,4 @@
 # -*- coding: utf-8 -*-
 """
-Copyright (C) 2020-2024 LiteyukiStudio. All Rights Reserved 
+本模块定义了粒子生成相关的工具
-
-@Time    : 2024/8/12 下午8:54
-@Author  : snowykami
-@Email   : snowykami@outlook.com
-@File    : __init__.py.py
-@Software: PyCharm
 """

mkdoc.bat

@@ -1,4 +1,4 @@
-python -m litedoc mbcp -o docs/api -l zh-Hans
+python -m litedoc mbcp -o docs/zh/api -l zh-Hans
 python -m litedoc mbcp -o docs/en/api -l en
 python -m litedoc mbcp -o docs/ja/api -l ja
 python -m litedoc mbcp -o docs/zht/api -l zh-Hant