✨ 支持Liteyuki Docstring

mbcp/__init__.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
 """
-本模块塞了一些预设的粒子生成器
+本模块是主模块，用于导入所有模块
 """
 from .mp_math import *

mbcp/mp_math/__init__.py

@@ -2,13 +2,13 @@
 """
 本包定义了一些常用的导入，可直接从`mbcp.mp_math`导入使用
 导入的类有：
-- `AnyAngle`：任意角
-- `CurveEquation`：曲线方程
-- `Line3`：三维直线
-- `Plane3`：三维平面
-- `Point3`：三维点
-- `Segment3`：三维线段
-- `Vector3`：三维向量
+- [`AnyAngle`](./angle#class-anyangle)：任意角度
+- [`CurveEquation`](./equation#class-curveequation)：曲线方程
+- [`Line3`](./line#class-line3)：三维直线
+- [`Plane3`](./plane#class-plane3)：三维平面
+- [`Point3`](./point#class-point3)：三维点
+- [`Segment3`](./segment#class-segment3)：三维线段
+- [`Vector3`](./vector#class-vector3)：三维向量
 """
 from .angle import AnyAngle
 from .const import *

mbcp/mp_math/equation.py

@@ -13,9 +13,9 @@ class CurveEquation:
         """
         曲线方程。
         Args:
-            x_func: x函数
-            y_func: y函数
-            z_func: z函数
+            x_func ([`OneVarFunc`](./mp_math_typing#var-onevarfunc)): x函数
+            y_func ([`OneVarFunc`](./mp_math_typing#var-onevarfunc)): y函数
+            z_func ([`OneVarFunc`](./mp_math_typing#var-onevarfunc)): z函数
         """
         self.x_func = x_func
         self.y_func = y_func
@@ -46,7 +46,7 @@ def get_partial_derivative_func(func: MultiVarsFunc, var: int | tuple[int, ...],
     > 目前数学界对于一个函数的导函数并没有通解的说法，因此该函数的稳定性有待提升
 
     Args:
-        func: 函数
+        func ([`MultiVarsFunc`](./mp_math_typing#var-multivarsfunc)): N元函数
         var: 变量位置，可为整数(一阶偏导)或整数元组(高阶偏导)
         epsilon: 偏移量
     Returns:

mbcp/mp_math/function.py

@@ -15,8 +15,8 @@ def cal_gradient_3vf(func: ThreeSingleVarsFunc, p: Point3, epsilon: float = EPSI
     > 已知一个函数$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: 点
+        func ([`ThreeSingleVarsFunc`](./mp_math_typing#var-threesinglevarsfunc)): 三元函数
+        p ([`Point3`](./point#class-point3)): 点
         epsilon: 偏移量
     Returns:
         梯度
@@ -33,8 +33,8 @@ def curry(func: MultiVarsFunc, *args: Var) -> OneVarFunc:
     > [!tip]
     > 有关函数柯里化，可参考[函数式编程--柯理化（Currying）](https://zhuanlan.zhihu.com/p/355859667)
     Args:
-        func: 函数
-        *args: 参数
+        func ([`MultiVarsFunc`](./mp_math_typing#var-multivarsfunc)): 函数
+        *args ([`Var`](./mp_math_typing#var-var)): 参数
     Returns:
         柯里化后的函数
     Examples:

mbcp/mp_math/line.py

@@ -20,8 +20,8 @@ class Line3:
         """
         三维空间中的直线。由一个点和一个方向向量确定。
         Args:
-            point: 直线上的一点
-            direction: 直线的方向向量
+            point ([`Point3`](./point#class-point3)): 直线上的一点
+            direction ([`Vector3`](./vector#class-vector3)): 方向向量
         """
         self.point = point
         self.direction = direction
@@ -30,10 +30,10 @@ class Line3:
         """
         判断两条直线是否近似相等。
         Args:
-            other: 另一条直线
-            epsilon: 误差
+            other ([`Line3`](./line#class-line3)): 另一条直线
+            epsilon ([`float`](https://docs.python.org/3/library/functions.html#float)): 误差
         Returns:
-            是否近似相等
+            [`bool`](https://docs.python.org/3/library/functions.html#bool): 是否近似相等
         """
         return self.is_approx_parallel(other, epsilon) and (self.point - other.point).is_approx_parallel(self.direction, epsilon)
 
@@ -41,11 +41,9 @@ class Line3:
         """
         计算直线和直线之间的夹角。
         Args:
-            other: 另一条直线
+            other ([`Line3`](./line#class-line3)): 另一条直线
         Returns:
-            夹角弧度
-        Raises:
-            TypeError: 不支持的类型
+            [`AnyAngle`](./angle#class-anyangle): 夹角
         """
         return self.direction.cal_angle(other.direction)
 
@@ -53,12 +51,11 @@ class Line3:
         """
         计算直线和直线或点之间的距离。
         Args:
-            other: 平行直线或点
-
+            other ([`Line3`](./line#class-line3) | [`Point3`](./point#class-point3)): 另一条直线或点
         Returns:
-            距离
+            [`float`](https%3A//docs.python.org/3/library/functions.html#float): 距离
         Raises:
-            TypeError: 不支持的类型
+            [`TypeError`](https%3A//docs.python.org/3/library/exceptions.html#TypeError): 不支持的类型
         """
         if isinstance(other, Line3):
             # 相交/重合 = 0；平行和异面需要计算距离
@@ -84,12 +81,12 @@ class Line3:
         """
         计算两条直线的交点。
         Args:
-            other: 另一条直线
+            other ([`Line3`](./line#class-line3)): 另一条直线
         Returns:
-            交点
+            [`Point3`](./point#class-point3): 交点
         Raises:
-            ValueError: 直线平行
-            ValueError: 直线不共面
+            [`ValueError`](https%3A//docs.python.org/3/library/exceptions.html#TypeError): 直线平行
+            `ValueError`: 直线不共面
         """
         if self.is_parallel(other):
             raise ValueError("Lines are parallel and do not intersect.")
@@ -102,9 +99,9 @@ class Line3:
         """
         计算直线经过指定点p的垂线。
         Args:
-            point: 指定点
+            point ([`Point3`](./point#class-point3)): 指定点
         Returns:
-            垂线
+            [`Line3`](./line#class-line3): 垂线
         """
         return Line3(point, self.direction.cross(point - self.point))
 
@@ -112,9 +109,9 @@ class Line3:
         """
         获取直线上的点。同一条直线，但起始点和方向向量不同，则同一个t对应的点不同。
         Args:
-            t: 参数t
+            t ([`RealNumber`](./mp_math_typing#var-realnumber)): 参数t
         Returns:
-            点
+            [`Point3`](./point#class-point3): 点
         """
         return self.point + t * self.direction
 
@@ -122,7 +119,7 @@ class Line3:
         """
         获取直线的参数方程。
         Returns:
-            x(t), y(t), z(t)
+            [`tuple`](https%3A//docs.python.org/3/library/stdtypes.html#tuple)[[`OneSingleVarFunc`](./mp_math_typing#var-onesinglevarfunc), `OneSingleVarFunc`, `OneSingleVarFunc`]: 参数方程
         """
         return (lambda t: self.point.x + self.direction.x * t,
                 lambda t: self.point.y + self.direction.y * t,
@@ -132,10 +129,10 @@ class Line3:
         """
         判断两条直线是否近似平行。
         Args:
-            other: 另一条直线
-            epsilon: 误差
+            other ([`Line3`](./line#class-line3)): 另一条直线
+            epsilon ([`float`](https%3A//docs.python.org/3/library/functions.html#float)): 误差
         Returns:
-            是否近似平行
+            [`bool`](https%3A//docs.python.org/3/library/functions.html#bool): 是否近似平行
         """
         return self.direction.is_approx_parallel(other.direction, epsilon)
 
@@ -143,9 +140,9 @@ class Line3:
         """
         判断两条直线是否平行。
         Args:
-            other: 另一条直线
+            other ([`Line3`](./line#class-line3)): 另一
         Returns:
-            是否平行
+            [`bool`](https%3A//docs.python.org/3/library/functions.html#bool): 是否平行
         """
         return self.direction.is_parallel(other.direction)
 
@@ -153,9 +150,9 @@ class Line3:
         """
         判断两条直线是否共线。
         Args:
-            other: 另一条直线
+            other ([`Line3`](./line#class-line3)): 另一
         Returns:
-            是否共线
+            [`bool`](https%3A//docs.python.org/3/library/functions.html#bool): 是否共线
         """
         return self.is_parallel(other) and (self.point - other.point).is_parallel(self.direction)
 
@@ -163,9 +160,9 @@ class Line3:
         """
         判断点是否在直线上。
         Args:
-            point: 点
+            point ([`Point3`](./point#class-point3)): 点
         Returns:
-            是否在直线上
+            [`bool`](https%3A//docs.python.org/3/library/functions.html#bool): 是否在直线上
         """
         return (point - self.point).is_parallel(self.direction)
 
@@ -174,9 +171,9 @@ class Line3:
         判断两条直线是否共面。
         充要条件：两直线方向向量的叉乘与两直线上任意一点的向量的点积为0。
         Args:
-            other: 另一条直线
+            other ([`Line3`](./line#class-line3)): 另一
         Returns:
-            是否共面
+            [`bool`](https%3A//docs.python.org/3/library/functions.html#bool): 是否共面
         """
         return self.direction.cross(other.direction) @ (self.point - other.point) == 0
 
@@ -203,10 +200,10 @@ class Line3:
         """
         工厂函数 由两点构造直线。
         Args:
-            p1: 点1
-            p2: 点2
+            p1 ([`Point3`](./point#class-point3)): 点1
+            p2 ([`Point3`](./point#class-point3)): 点2
         Returns:
-            直线
+            [`Line3`](./line#class-line3): 直线
         """
         direction = p2 - p1
         return cls(p1, direction)
@@ -215,9 +212,9 @@ class Line3:
         """
         计算两条直线点集合的交集。重合线返回自身，平行线返回None，交线返回交点。
         Args:
-            other: 另一条直线
+            other ([`Line3`](./line#class-line3)): 另一条直线
         Returns:
-            交点
+            [`Line3`](./line#class-line3) | [`Point3`](./point#class-point3) | [`None`](https://docs.python.org/3/library/constants.html#None): 交集
         """
         if self.is_collinear(other):
             return self
@@ -232,10 +229,9 @@ class Line3:
 
         v1 // v2 ∧ (p1 - p2) // v1
         Args:
-            other:
-
+            other ([`Line3`](./line#class-line3)): 另一条直线
         Returns:
-
+            [`bool`](https%3A//docs.python.org/3/library/functions.html#bool): 是否等价
         """
         return self.direction.is_parallel(other.direction) and (self.point - other.point).is_parallel(self.direction)
 
@@ -243,7 +239,7 @@ class Line3:
         """
         返回点向式（x-x0）
         Returns:
-
+            [`str`](https%3A//docs.python.org/3/library/functions.html#str): 点向式
         """
         s = "Line3: "
         if self.direction.x != 0:
@@ -255,4 +251,9 @@ class Line3:
         return s
 
     def __repr__(self):
+        """
+        返回直线的字符串表示。
+        Returns:
+            [`str`](https%3A//docs.python.org/3/library/functions.html#str) 字符串表示
+        """
         return f"Line3({self.point}, {self.direction})"

mbcp/mp_math/plane.py

@@ -21,10 +21,10 @@ class Plane3:
         """
         平面方程：ax + by + cz + d = 0
         Args:
-            a: x系数
-            b: y系数
-            c: z系数
-            d: 常数项
+            a ([`float`](https%3A//docs.python.org/3/library/functions.html#float)): x系数
+            b (`float`): y系数
+            c (`float`): z系数
+            d (`float`): 常数项
         """
         self.a = a
         self.b = b
@@ -35,9 +35,9 @@ class Plane3:
         """
         判断两个平面是否近似相等。
         Args:
-            other: 另一个平面
+            other ([`Plane3`](./plane#class-plane3)): 另一个平面
         Returns:
-            是否近似相等
+            [`bool`](https://docs.python.org/3/library/functions.html#bool): 是否近似相等
         """
         if self.a != 0:
             k = other.a / self.a
@@ -55,11 +55,11 @@ class Plane3:
         """
         计算平面与平面之间的夹角。
         Args:
-            other: 另一个平面
+            other ([`Line3`](./line#class-line3) | [`Plane3`](./plane#class-plane3)): 另一个平面或直线
         Returns:
-            夹角弧度
+            [`AnyAngle`](./angle#class-anyangle): 夹角
         Raises:
-            TypeError: 不支持的类型
+            [`TypeError`](https%3A//docs.python.org/3/library/exceptions.html#TypeError): 不支持的类型
         """
         if isinstance(other, Line3):
             return self.normal.cal_angle(other.direction).complementary
@@ -72,11 +72,11 @@ class Plane3:
         """
         计算平面与平面或点之间的距离。
         Args:
-            other: 另一个平面或点
+            other ([`Plane3`](./plane#class-plane3) | [`Point3`](./point#class-point3)): 另一个平面或点
         Returns:
-            距离
+            [`float`](https%3A//docs.python.org/3/library/functions.html#float): 距离
         Raises:
-            TypeError: 不支持的类型
+            [`TypeError`](https%3A//docs.python.org/3/library/exceptions.html#TypeError): 不支持的类型
         """
         if isinstance(other, Plane3):
             return 0
@@ -89,10 +89,11 @@ class Plane3:
         """
         计算两平面的交线。
         Args:
-            other: 另一个平面
+            other ([`Plane3`](./plane#class-plane3)): 另一个平面
         Returns:
-            两平面的交线
+            [`Line3`](./line#class-line3): 交线
         Raises:
+            [`ValueError`](https%3A//docs.python.org/3/library/exceptions.html#ValueError): 平面平行且无交线
         """
         if self.normal.is_parallel(other.normal):
             raise ValueError("Planes are parallel and have no intersection.")
@@ -121,11 +122,11 @@ class Plane3:
         """
         计算平面与直线的交点。
         Args:
-            other: 不与平面平行或在平面上的直线
+            other ([`Line3`](./line#class-line3)): 直线
         Returns:
-            交点
+            [`Point3`](./point#class-point3): 交点
         Raises:
-            ValueError: 平面与直线平行或重合
+            [`ValueError`](https%3A//docs.python.org/3/library/exceptions.html#ValueError): 平面与直线平行或重合
         """
         # 若平面的法向量与直线方向向量垂直，则直线与平面平行或重合
         if self.normal @ other.direction == 0:
@@ -141,9 +142,9 @@ class Plane3:
         """
         计算平行于该平面且过指定点的平面。
         Args:
-            point: 指定点
+            point ([`Point3`](./point#class-point3)): 指定点
         Returns:
-            所求平面
+            [`Plane3`](./plane#class-plane3): 平面
         """
         return Plane3.from_point_and_normal(point, self.normal)
 
@@ -151,9 +152,9 @@ class Plane3:
         """
         判断两个平面是否平行。
         Args:
-            other: 另一个平面
+            other ([`Plane3`](./plane#class-plane3)): 另一个平面
         Returns:
-            是否平行
+            [`bool`](https%3A//docs.python.org/3/library/functions.html#bool): 是否平行
         """
         return self.normal.is_parallel(other.normal)
 
@@ -162,7 +163,7 @@ class Plane3:
         """
         平面的法向量。
         Returns:
-            法向量
+            [`Vector3`](./vector#class-vector3): 法向量
         """
         return Vector3(self.a, self.b, self.c)
 
@@ -171,10 +172,10 @@ class Plane3:
         """
         工厂函数 由点和法向量构造平面(点法式构造)。
         Args:
-            point: 平面上的一点
-            normal: 法向量
+            point ([`Point3`](./point#class-point3)): 平面上一点
+            normal ([`Vector3`](./vector#class-vector3)): 法向量
         Returns:
-            平面
+            [`Plane3`](./plane#class-plane3): 平面
         """
         a, b, c = normal.x, normal.y, normal.z
         d = -a * point.x - b * point.y - c * point.z  # d = -ax - by - cz
@@ -185,9 +186,9 @@ class Plane3:
         """
         工厂函数 由三点构造平面。
         Args:
-            p1: 点1
-            p2: 点2
-            p3: 点3
+            p1 ([`Point3`](./point#class-point3)): 点1
+            p2 (`Point3`): 点2
+            p3 (`Point3`): 点3
         Returns:
             平面
         """
@@ -203,8 +204,8 @@ class Plane3:
         """
         工厂函数 由两直线构造平面。
         Args:
-            l1: 直线1
-            l2: 直线2
+            l1 ([`Line3`](./line#class-line3)): 直线
+            l2 (`Line3`): 直线
         Returns:
             平面
         """
@@ -219,17 +220,27 @@ class Plane3:
         """
         工厂函数 由点和直线构造平面。
         Args:
-            point: 面上一点
-            line: 面上直线，不包含点
+            point ([`Point3`](./point#class-point3)): 平面上一点
+            line ([`Line3`](./line#class-line3)): 直线
         Returns:
             平面
         """
         return cls.from_point_and_normal(point, line.direction)
 
     def __repr__(self):
+        """
+        返回平面的字符串表示。
+        Returns:
+            [`str`](https%3A//docs.python.org/3/library/functions.html#str): 字符串表示
+        """
         return f"Plane3({self.a}, {self.b}, {self.c}, {self.d})"
 
     def __str__(self):
+        """
+        返回平面的字符串表示。
+        Returns:
+            [`str`](https%3A//docs.python.org/3/library/functions.html#str): 字符串表示
+        """
         s = "Plane3: "
         if self.a != 0:
             s += f"{sign(self.a, only_neg=True)}{abs(self.a)}x"
@@ -253,9 +264,11 @@ class Plane3:
         """
         取两平面的交集（人话：交线）
         Args:
-            other:
+            other ([`Line3`](./line#class-line3) | [`Plane3`](./plane#class-plane3)): 另一个平面或直线
         Returns:
-            不平行平面的交线，平面平行返回None
+            [`Line3`](./line#class-line3) | [`Point3`](./point#class-point3) | [`None`](https%3A//docs.python.org/3/library/constants.html#None): 交集
+        Raises:
+            [`TypeError`](https%3A//docs.python.org/3/library/exceptions.html#TypeError): 不支持的类型
         """
         if isinstance(other, Plane3):
             if self.normal.is_parallel(other.normal):
@@ -269,6 +282,13 @@ class Plane3:
             raise TypeError(f"unsupported operand type(s) for &: 'Plane3' and '{type(other)}'")
 
     def __eq__(self, other) -> bool:
+        """
+        判断两个平面是否等价。
+        Args:
+            other ([`Plane3`](./plane#class-plane3)): 另一个平面
+        Returns:
+            [`bool`](https%3A//docs.python.org/3/library/functions.html#bool): 是否等价
+        """
         return self.approx(other)
 
     def __rand__(self, other: 'Line3') -> 'Point3':

mbcp/mp_math/point.py

@@ -16,9 +16,9 @@ class Point3:
         """
         笛卡尔坐标系中的点。
         Args:
-            x: x 坐标
-            y: y 坐标
-            z: z 坐标
+            x ([`float`](https://docs.python.org/3/library/functions.html#float)): x 坐标
+            y (`float`): y 坐标
+            z (`float`): z 坐标
         """
         self.x = x
         self.y = y
@@ -28,15 +28,19 @@ class Point3:
         """
         判断两个点是否近似相等。
         Args:
-            other:
-            epsilon:
-
+            other ([`Point3`](./point#class-point3)): 另一个点
+            epsilon ([`float`](https://docs.python.org/3/library/functions.html#float)): 误差
         Returns:
-            是否近似相等
+            [`bool`](https://docs.python.org/3/library/functions.html#bool): 是否近似相等
         """
         return all([abs(self.x - other.x) < epsilon, abs(self.y - other.y) < epsilon, abs(self.z - other.z) < epsilon])
 
     def __str__(self):
+        """
+        点的字符串表示。
+        Returns:
+            [`str`](https://docs.python.org/3/library/functions.html#str): 字符串
+        """
         return f"Point3({self.x}, {self.y}, {self.z})"
 
     @overload
@@ -52,8 +56,9 @@ class Point3:
         P + V -> P
         P + P -> P
         Args:
-            other:
+            other ([`Vector3`](./vector#class-vector3) | [`Point3`](./point#class-point3)): 另一个点或向量
         Returns:
+            [`Point3`](./point#class-point3): 新的点
         """
         return Point3(self.x + other.x, self.y + other.y, self.z + other.z)
 
@@ -61,8 +66,9 @@ class Point3:
         """
         判断两个点是否相等。
         Args:
-            other:
+            other ([`Point3`](./point#class-point3)): 另一个点
         Returns:
+            [`bool`](https://docs.python.org/3/library/functions.html#bool): 是否相等
         """
         return approx(self.x, other.x) and approx(self.y, other.y) and approx(self.z, other.z)
 
@@ -70,11 +76,11 @@ class Point3:
         """
         P - P -> V
 
-        P - V -> P  已在 :class:`Vector3` 中实现
+        P - V -> P  已在 [`Vector3`](./vector#class-vector3) 中实现
         Args:
-            other:
+            other ([`Point3`](./point#class-point3)): 另一个点
         Returns:
-
+            [`Vector3`](./vector#class-vector3): 新的向量
         """
         from .vector import Vector3
         return Vector3(self.x - other.x, self.y - other.y, self.z - other.z)

mbcp/mp_math/segment.py

@@ -14,8 +14,9 @@ class Segment3:
     def __init__(self, p1: "Point3", p2: "Point3"):
         """
         三维空间中的线段。
-        :param p1:
-        :param p2:
+        Args:
+            p1 ([`Point3`](./point#class-point3)): 线段的一个端点
+            p2 ([`Point3`](./point#class-point3)): 线段的另一个端点
         """
         self.p1 = p1
         self.p2 = p2
@@ -28,7 +29,17 @@ class Segment3:
         self.midpoint = Point3((self.p1.x + self.p2.x) / 2, (self.p1.y + self.p2.y) / 2, (self.p1.z + self.p2.z) / 2)
 
     def __repr__(self):
+        """
+        线段的字符串表示(可执行)。
+        Returns:
+            [`str`](https://docs.python.org/3/library/functions.html#str): 字符串
+        """
         return f"Segment3({self.p1}, {self.p2})"
 
     def __str__(self):
+        """
+        线段的字符串表示。
+        Returns:
+            [`str`](https://docs.python.org/3/library/functions.html#str): 字符串
+        """
         return f"Segment3({self.p1} -> {self.p2})"

mbcp/mp_math/utils.py

@@ -18,12 +18,12 @@ def clamp(x: float, min_: float, max_: float) -> float:
     """
     区间限定函数
     Args:
-        x: 待限定的值
-        min_: 最小值
-        max_: 最大值
+        x ([`float`](https://docs.python.org/3/library/functions.html#float)): 值
+        min_ (`float`): 最小值
+        max_ (`float`): 最大值
 
     Returns:
-        限制后的值
+        `float`: 限定在区间内的值
     """
     return max(min(x, max_), min_)
 
@@ -31,10 +31,14 @@ def clamp(x: float, min_: float, max_: float) -> float:
 class Approx:
     """
     用于近似比较对象
-
     已实现对象 实数 Vector3 Point3 Plane3 Line3
     """
     def __init__(self, value: RealNumber):
+        """
+        用于近似比较对象
+        Args:
+            value ([`RealNumber`](./mp_math_typing#realnumber)): 实数
+        """
         self.value = value
 
     def __eq__(self, other):
@@ -60,11 +64,11 @@ def approx(x: float, y: float = 0.0, epsilon: float = APPROX) -> bool:
     """
     判断两个数是否近似相等。或包装一个实数，用于判断是否近似于0。
     Args:
-        x: 数1
-        y: 数2
-        epsilon: 误差
+        x ([`float`](https://docs.python.org/3/library/functions.html#float)): 数1
+        y (`float`): 数2
+        epsilon (`float`): 误差
     Returns:
-        是否近似相等
+        [`bool`](https://docs.python.org/3/library/functions.html#bool): 是否近似相等
     """
     return abs(x - y) < epsilon
 
@@ -72,10 +76,10 @@ def approx(x: float, y: float = 0.0, epsilon: float = APPROX) -> bool:
 def sign(x: float, only_neg: bool = False) -> str:
     """获取数的符号。
     Args:
-        x: 数
-        only_neg: 是否只返回负数的符号
+        x ([`float`](https://docs.python.org/3/library/functions.html#float)): 数
+        only_neg ([`bool`](https://docs.python.org/3/library/functions.html#bool)): 是否只返回负数的符号
     Returns:
-        符号 + - ""
+        [`str`](https://docs.python.org/3/library/functions.html#str): 符号 + - ""
     """
     if x > 0:
         return "+" if not only_neg else ""
@@ -91,10 +95,10 @@ def sign_format(x: float, only_neg: bool = False) -> str:
     1 -> +1
     0 -> ""
     Args:
-        x: 数
-        only_neg: 是否只返回负数的符号
+        x ([`float`](https://docs.python.org/3/library/functions.html#float)): 数
+        only_neg ([`bool`](https://docs.python.org/3/library/functions.html#bool)): 是否只返回负数的符号
     Returns:
-        符号 + - ""
+        [`str`](https://docs.python.org/3/library/functions.html#str): 符号 + - ""
     """
     if x > 0:
         return f"+{x}" if not only_neg else f"{x}"

mbcp/mp_math/vector.py

@@ -43,9 +43,9 @@ class Vector3:
         """
         计算两个向量之间的夹角。
         Args:
-            other: 另一个向量
+            other ([`Vector3`](#class-vector3)): 另一个向量
         Returns:
-            夹角
+            [`AnyAngle`](./angle#class-anyangle): 夹角
         """
         return AnyAngle(math.acos(self @ other / (self.length * other.length)), is_radian=True)
 
@@ -65,9 +65,9 @@ class Vector3:
         ``x2 y2 z2``
 
         Args:
-            other:
+            other ([`Vector3`](#class-vector3)): 另一个向量
         Returns:
-            行列式的结果
+            [`Vector3`](#class-vector3): 叉乘结果
         """
         return Vector3(self.y * other.z - self.z * other.y,
                        self.z * other.x - self.x * other.z,
@@ -77,10 +77,10 @@ class Vector3:
         """
         判断两个向量是否近似平行。
         Args:
-            other: 另一个向量
-            epsilon: 允许的误差
+            other ([`Vector3`](#class-vector3)): 另一个向量
+            epsilon ([`float`](https%3A//docs.python.org/3/library/functions.html#float)): 误差
         Returns:
-            是否近似平行
+            [`bool`](https%3A//docs.python.org/3/library/functions.html#bool): 是否近似平行
         """
         return self.cross(other).length < epsilon
 
@@ -88,9 +88,9 @@ class Vector3:
         """
         判断两个向量是否平行。
         Args:
-            other: 另一个向量
+            other ([`Vector3`](#class-vector3)): 另一个向量
         Returns:
-            是否平行
+            [`bool`](https%3A//docs.python.org/3/library/functions.html#bool): 是否平行
         """
         return self.cross(other).approx(zero_vector3)
 
@@ -110,6 +110,7 @@ class Vector3:
         """
         返回numpy数组
         Returns:
+            [`np.ndarray`](https%3A//numpy.org/doc/stable/reference/generated/numpy.ndarray.html): numpy数组
         """
 
         return np.array([self.x, self.y, self.z])
@@ -119,7 +120,7 @@ class Vector3:
         """
         向量的模。
         Returns:
-            模
+            [`float`](https%3A//docs.python.org/3/library/functions.html#float): 模
         """
         return math.sqrt(self.x ** 2 + self.y ** 2 + self.z ** 2)
 
@@ -128,7 +129,7 @@ class Vector3:
         """
         获取该向量的单位向量。
         Returns:
-            单位向量
+            [`Vector3`](#class-vector3): 单位向量
         """
         return self / self.length
 
@@ -148,9 +149,9 @@ class Vector3:
         V + P -> P\n
         V + V -> V
         Args:
-            other:
+            other ([`Vector3`](#class-vector3) | [`Point3`](./point#class-point3)): 另一个向量或点
         Returns:
-
+            [`Vector3`](#class-vector3) | [`Point3`](./point#class-point3): 新的向量或点
         """
         if isinstance(other, Vector3):
             return Vector3(self.x + other.x, self.y + other.y, self.z + other.z)
@@ -163,9 +164,9 @@ class Vector3:
         """
         判断两个向量是否相等。
         Args:
-            other:
+            other ([`Vector3`](#class-vector3)): 另一个向量
         Returns:
-            是否相等
+            [`bool`](https%3A//docs.python.org/3/library/functions.html#bool): 是否相等
         """
         return approx(self.x, other.x) and approx(self.y, other.y) and approx(self.z, other.z)
 
@@ -173,8 +174,10 @@ class Vector3:
         """
         P + V -> P\n
         别去点那边实现了。
-        :param other:
-        :return:
+        Args:
+            other ([`Point3`](./point#class-point3)): 另一个点
+        Returns:
+            [`Point3`](./point#class-point3): 新的点
         """
         return Point3(self.x + other.x, self.y + other.y, self.z + other.z)
 
@@ -191,8 +194,9 @@ class Vector3:
         V - P -> P\n
         V - V -> V
         Args:
-            other:
+            other ([`Vector3`](#class-vector3) | [`Point3`](./point#class-point3)): 另一个向量或点
         Returns:
+            [`Vector3`](#class-vector3) | [`Point3`](./point#class-point3): 新的向量
         """
         if isinstance(other, Vector3):
             return Vector3(self.x - other.x, self.y - other.y, self.z - other.z)
@@ -205,9 +209,9 @@ class Vector3:
         """
         P - V -> P
         Args:
-            other:
+            other ([`Point3`](./point#class-point3)): 另一个点
         Returns:
-
+            [`Point3`](./point#class-point3): 新的点
         """
 
         if isinstance(other, Point3):
@@ -227,9 +231,9 @@ class Vector3:
         """
         数组运算 非点乘。点乘使用@，叉乘使用cross。
         Args:
-            other:
-
+            other ([`Vector3`](#class-vector3) | [`float`](https%3A//docs.python.org/3/library/functions.html#float)): 另一个向量或数
         Returns:
+            [`Vector3`](#class-vector): 数组运算结果
         """
 
         if isinstance(other, Vector3):
@@ -246,21 +250,37 @@ class Vector3:
         """
         点乘。
         Args:
-            other:
+            other ([`Vector3`](#class-vector3)): 另一个向量
         Returns:
+            [`float`](https%3A//docs.python.org/3/library/functions.html#float): 点乘结果
         """
         return self.x * other.x + self.y * other.y + self.z * other.z
 
     def __truediv__(self, other: RealNumber) -> 'Vector3':
         return Vector3(self.x / other, self.y / other, self.z / other)
 
-    def __neg__(self):
+    def __neg__(self) -> 'Vector3':
+        """
+        取负。
+        Returns:
+            [`Vector3`](#class-vector3): 负向量
+        """
         return Vector3(-self.x, -self.y, -self.z)
 
-    def __repr__(self):
+    def __repr__(self) -> str:
+        """
+        向量的字符串表示(可执行)。
+        Returns:
+            [`str`](https%3A//docs.python.org/3/library/functions.html#str): 字符串
+        """
         return f"Vector3({self.x}, {self.y}, {self.z})"
 
-    def __str__(self):
+    def __str__(self) -> str:
+        """
+        向量的字符串表示。
+        Returns:
+            [`str`](https%3A//docs.python.org/3/library/functions.html#str): 字符串
+        """
         return f"Vector3({self.x}, {self.y}, {self.z})"
 
 

mbcp/presets/__init__.py

@@ -1,10 +1,4 @@
 # -*- coding: utf-8 -*-
 """
-Copyright (C) 2020-2024 LiteyukiStudio. All Rights Reserved 
-
-@Time    : 2024/8/12 下午9:12
-@Author  : snowykami
-@Email   : snowykami@outlook.com
-@File    : __init__.py
-@Software: PyCharm
+本模块塞了一些预设
 """