📝 构建文档测试

.github/workflows/deploy-docs.yml

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

.gitignore

@@ -11,4 +11,6 @@ pdm.lock
 node_modules/
 
 docs/.vitepress/dist
-docs/.vitepress/cache
+docs/.vitepress/cache
+
+litedoc/

docs/api/mp_math/equation.md

@@ -7,13 +7,13 @@ title: mbcp.mp_math.equation
 
 **说明**: 求N元函数一阶偏导函数。这玩意不太稳定，慎用。
 
-**返回**: 偏导函数
-
 **参数**:
 > - func: 函数  
 > - var: 变量位置，可为整数(一阶偏导)或整数元组(高阶偏导)  
 > - epsilon: 偏移量  
 
+**返回**: 偏导函数
+
 **引发**:
 > - ValueError  无效变量类型
 

docs/api/mp_math/line.md

@@ -35,12 +35,12 @@ def __init__(self, point: 'Point3', direction: 'Vector3'):
 
 **说明**: 判断两条直线是否近似相等。
 
-**返回**: 是否近似相等
-
 **参数**:
 > - other: 另一条直线  
 > - epsilon: 误差  
 
+**返回**: 是否近似相等
+
 
 <details>
 <summary> <b>源代码</b> </summary>
@@ -65,11 +65,11 @@ def approx(self, other: 'Line3', epsilon: float=APPROX) -> bool:
 
 **说明**: 计算直线和直线之间的夹角。
 
-**返回**: 夹角弧度
-
 **参数**:
 > - other: 另一条直线  
 
+**返回**: 夹角弧度
+
 **引发**:
 > - TypeError  不支持的类型
 
@@ -98,11 +98,11 @@ def cal_angle(self, other: 'Line3') -> 'AnyAngle':
 
 **说明**: 计算直线和直线或点之间的距离。
 
-**返回**: 距离
-
 **参数**:
 > - other: 平行直线或点  
 
+**返回**: 距离
+
 **引发**:
 > - TypeError  不支持的类型
 
@@ -144,11 +144,11 @@ def cal_distance(self, other: 'Line3 | Point3') -> float:
 
 **说明**: 计算两条直线的交点。
 
-**返回**: 交点
-
 **参数**:
 > - other: 另一条直线  
 
+**返回**: 交点
+
 **引发**:
 > - ValueError  直线平行
 > - ValueError  直线不共面
@@ -183,11 +183,11 @@ def cal_intersection(self, other: 'Line3') -> 'Point3':
 
 **说明**: 计算直线经过指定点p的垂线。
 
-**返回**: 垂线
-
 **参数**:
 > - point: 指定点  
 
+**返回**: 垂线
+
 
 <details>
 <summary> <b>源代码</b> </summary>
@@ -211,11 +211,11 @@ def cal_perpendicular(self, point: 'Point3') -> 'Line3':
 
 **说明**: 获取直线上的点。同一条直线，但起始点和方向向量不同，则同一个t对应的点不同。
 
-**返回**: 点
-
 **参数**:
 > - t: 参数t  
 
+**返回**: 点
+
 
 <details>
 <summary> <b>源代码</b> </summary>
@@ -262,12 +262,12 @@ def get_parametric_equations(self) -> tuple[OneSingleVarFunc, OneSingleVarFunc,
 
 **说明**: 判断两条直线是否近似平行。
 
-**返回**: 是否近似平行
-
 **参数**:
 > - other: 另一条直线  
 > - epsilon: 误差  
 
+**返回**: 是否近似平行
+
 
 <details>
 <summary> <b>源代码</b> </summary>
@@ -292,11 +292,11 @@ def is_approx_parallel(self, other: 'Line3', epsilon: float=1e-06) -> bool:
 
 **说明**: 判断两条直线是否平行。
 
-**返回**: 是否平行
-
 **参数**:
 > - other: 另一条直线  
 
+**返回**: 是否平行
+
 
 <details>
 <summary> <b>源代码</b> </summary>
@@ -320,11 +320,11 @@ def is_parallel(self, other: 'Line3') -> bool:
 
 **说明**: 判断两条直线是否共线。
 
-**返回**: 是否共线
-
 **参数**:
 > - other: 另一条直线  
 
+**返回**: 是否共线
+
 
 <details>
 <summary> <b>源代码</b> </summary>
@@ -348,11 +348,11 @@ def is_collinear(self, other: 'Line3') -> bool:
 
 **说明**: 判断点是否在直线上。
 
-**返回**: 是否在直线上
-
 **参数**:
 > - point: 点  
 
+**返回**: 是否在直线上
+
 
 <details>
 <summary> <b>源代码</b> </summary>
@@ -377,11 +377,11 @@ def is_point_on(self, point: 'Point3') -> bool:
 **说明**: 判断两条直线是否共面。
 充要条件：两直线方向向量的叉乘与两直线上任意一点的向量的点积为0。
 
-**返回**: 是否共面
-
 **参数**:
 > - other: 另一条直线  
 
+**返回**: 是否共面
+
 
 <details>
 <summary> <b>源代码</b> </summary>
@@ -438,12 +438,12 @@ def simplify(self):
 
 **说明**: 工厂函数 由两点构造直线。
 
-**返回**: 直线
-
 **参数**:
 > - p1: 点1  
 > - p2: 点2  
 
+**返回**: 直线
+
 
 <details>
 <summary> <b>源代码</b> </summary>
@@ -470,11 +470,11 @@ def from_two_points(cls, p1: 'Point3', p2: 'Point3') -> 'Line3':
 
 **说明**: 计算两条直线点集合的交集。重合线返回自身，平行线返回None，交线返回交点。
 
-**返回**: 交点
-
 **参数**:
 > - other: 另一条直线  
 
+**返回**: 交点
+
 
 <details>
 <summary> <b>源代码</b> </summary>

docs/api/mp_math/plane.md

@@ -41,11 +41,11 @@ def __init__(self, a: float, b: float, c: float, d: float):
 
 **说明**: 判断两个平面是否近似相等。
 
-**返回**: 是否近似相等
-
 **参数**:
 > - other: 另一个平面  
 
+**返回**: 是否近似相等
+
 
 <details>
 <summary> <b>源代码</b> </summary>
@@ -79,11 +79,11 @@ def approx(self, other: 'Plane3') -> bool:
 
 **说明**: 计算平面与平面之间的夹角。
 
-**返回**: 夹角弧度
-
 **参数**:
 > - other: 另一个平面  
 
+**返回**: 夹角弧度
+
 **引发**:
 > - TypeError  不支持的类型
 
@@ -117,11 +117,11 @@ def cal_angle(self, other: 'Line3 | Plane3') -> 'AnyAngle':
 
 **说明**: 计算平面与平面或点之间的距离。
 
-**返回**: 距离
-
 **参数**:
 > - other: 另一个平面或点  
 
+**返回**: 距离
+
 **引发**:
 > - TypeError  不支持的类型
 
@@ -155,11 +155,11 @@ def cal_distance(self, other: 'Plane3 | Point3') -> float:
 
 **说明**: 计算两平面的交线。
 
-**返回**: 两平面的交线
-
 **参数**:
 > - other: 另一个平面  
 
+**返回**: 两平面的交线
+
 
 <details>
 <summary> <b>源代码</b> </summary>
@@ -200,11 +200,11 @@ def cal_intersection_line3(self, other: 'Plane3') -> 'Line3':
 
 **说明**: 计算平面与直线的交点。
 
-**返回**: 交点
-
 **参数**:
 > - other: 不与平面平行或在平面上的直线  
 
+**返回**: 交点
+
 **引发**:
 > - ValueError  平面与直线平行或重合
 
@@ -237,11 +237,11 @@ def cal_intersection_point3(self, other: 'Line3') -> 'Point3':
 
 **说明**: 计算平行于该平面且过指定点的平面。
 
-**返回**: 所求平面
-
 **参数**:
 > - point: 指定点  
 
+**返回**: 所求平面
+
 
 <details>
 <summary> <b>源代码</b> </summary>
@@ -265,11 +265,11 @@ def cal_parallel_plane3(self, point: 'Point3') -> 'Plane3':
 
 **说明**: 判断两个平面是否平行。
 
-**返回**: 是否平行
-
 **参数**:
 > - other: 另一个平面  
 
+**返回**: 是否平行
+
 
 <details>
 <summary> <b>源代码</b> </summary>
@@ -319,12 +319,12 @@ def normal(self) -> 'Vector3':
 
 **说明**: 工厂函数 由点和法向量构造平面(点法式构造)。
 
-**返回**: 平面
-
 **参数**:
 > - point: 平面上的一点  
 > - normal: 法向量  
 
+**返回**: 平面
+
 
 <details>
 <summary> <b>源代码</b> </summary>
@@ -353,13 +353,13 @@ def from_point_and_normal(cls, point: 'Point3', normal: 'Vector3') -> 'Plane3':
 
 **说明**: 工厂函数 由三点构造平面。
 
-**返回**: 平面
-
 **参数**:
 > - p1: 点1  
 > - p2: 点2  
 > - p3: 点3  
 
+**返回**: 平面
+
 
 <details>
 <summary> <b>源代码</b> </summary>
@@ -390,12 +390,12 @@ def from_three_points(cls, p1: 'Point3', p2: 'Point3', p3: 'Point3') -> 'Plane3'
 
 **说明**: 工厂函数 由两直线构造平面。
 
-**返回**: 平面
-
 **参数**:
 > - l1: 直线1  
 > - l2: 直线2  
 
+**返回**: 平面
+
 
 <details>
 <summary> <b>源代码</b> </summary>
@@ -426,12 +426,12 @@ def from_two_lines(cls, l1: 'Line3', l2: 'Line3') -> 'Plane3':
 
 **说明**: 工厂函数 由点和直线构造平面。
 
-**返回**: 平面
-
 **参数**:
 > - point: 面上一点  
 > - line: 面上直线，不包含点  
 
+**返回**: 平面
+
 
 <details>
 <summary> <b>源代码</b> </summary>
@@ -485,11 +485,11 @@ def __and__(self, other: 'Plane3') -> 'Line3 | None':
 
 **说明**: 取两平面的交集（人话：交线）
 
-**返回**: 不平行平面的交线，平面平行返回None
-
 **参数**:
 > - other:   
 
+**返回**: 不平行平面的交线，平面平行返回None
+
 
 <details>
 <summary> <b>源代码</b> </summary>