.github/workflows/website.yml

@@ -18,7 +18,6 @@ jobs:
     - uses: actions/setup-node@v3.1.1
     - name: Retype build
       run: |
-        python scripts/gen_docs.py
         cd docs
         npm install retypeapp --global
         retype build

.gitignore

@@ -36,4 +36,3 @@ docs/references.md
 .vs
 
 tests/00_tmp.py
-docs/C-API/functions.md

docs/C-API/introduction.md

@@ -5,15 +5,3 @@ order: 10
 ---
 
 TBA
-
-
-### `PY_RAISE` macro
-
-Mark a function that can raise an exception on failure.
-
-+ If the function returns `bool`, then `false` means an exception is raised.
-+ If the function returns `int`, then `-1` means an exception is raised.
-
-### `PY_RETURN` macro
-
-Mark a function that can store a value in `py_retval()` on success.

docs/modules/base64.md

@@ -0,0 +1,13 @@
+---
+icon: package
+label: base64
+---
+
+### `base64.b64encode(b: bytes) -> bytes`
+
+Encode bytes-like object `b` using the standard Base64 alphabet.
+
+### `base64.b64decode(b: bytes) -> bytes`
+
+Decode Base64 encoded bytes-like object `b`.
+

docs/modules/bisect.md

@@ -22,7 +22,3 @@ If x is already in a, insert it to the left of the leftmost x.
 Insert item `x` in list `a`, and keep it sorted assuming `a` is sorted.
 
 If x is already in a, insert it to the right of the rightmost x.
-
-#### Source code
-
-:::code source="../../python/bisect.py" :::

docs/modules/cmath.md

@@ -3,10 +3,10 @@ icon: package
 label: cmath
 ---
 
+!!!
+This module is experimental and may have bugs or other issues.
+!!!
+
 Mathematical functions for complex numbers.
 
 https://docs.python.org/3/library/cmath.html
-
-#### Source code
-
-:::code source="../../python/cmath.py" :::

docs/modules/collections.md

@@ -3,6 +3,7 @@ icon: package
 label: collections
 ---
 
+
 ### `collections.Counter(iterable)`
 
 Return a `dict` containing the counts of each element in `iterable`.
@@ -14,7 +15,3 @@ A double-ended queue.
 ### `collections.defaultdict`
 
 A dictionary that returns a default value when a key is not found.
-
-#### Source code
-
-:::code source="../../python/collections.py" :::

docs/modules/dataclasses.md

@@ -5,7 +5,7 @@ label: dataclasses
 
 ### `dataclasses.dataclass`
 
-A decorator that is used to add special method to classes, including `__init__`, `__repr__` and `__eq__`.
+A decorator that is used to add generated special method to classes, including `__init__`, `__repr__` and `__eq__`.
 
 ### `dataclasses.asdict(obj) -> dict`
 

docs/modules/datetime.md

@@ -10,7 +10,3 @@ Returns the current date and time as a `datetime` object.
 ### `date.today()`
 
 Returns the current local date as a `date` object.
-
-#### Source code
-
-:::code source="../../python/datetime.py" :::

docs/modules/functools.md

@@ -14,8 +14,3 @@ Apply a function of two arguments cumulatively to the items of a sequence, from
 ### `functools.partial(f, *args, **kwargs)`
 
 Return a new partial object which when called will behave like `f` called with the positional arguments `args` and keyword arguments `kwargs`. If more arguments are supplied to the call, they are appended to `args`. If additional keyword arguments are supplied, they extend and override `kwargs`.
-
-
-#### Source code
-
-:::code source="../../python/functools.py" :::

docs/modules/heapq.md

@@ -22,7 +22,3 @@ Push `item` on the heap, then pop and return the smallest item from the heap. Th
 ### `heapq.heapreplace(heap, item)`
 
 Pop and return the smallest item from the heap, and also push the new item. The heap size doesn’t change. If the heap is empty, IndexError is raised.
-
-#### Source code
-
-:::code source="../../python/heapq.py" :::

docs/modules/json.md

@@ -3,7 +3,13 @@ icon: package
 label: json
 ---
 
-### `json.loads(data: str)`
+pkpy has two JSON modules.
+1. The built-in JSON module is always available and can be imported via `import json`.
+2. After `v1.2.7`, you can set `PK_USE_CJSON` to `ON` in CMakeLists.txt to enable an alternative JSON module `cjson`.
+
+**Their interfaces are the same.** `cjson` is faster while the built-in `json` is more stable since it was developed earlier.
+
+### `json.loads(data: str | bytes)`
 
 Decode a JSON string into a python object.
 

docs/modules/linalg.md

@@ -9,4 +9,166 @@ This classes adopt `torch`'s naming convention. Methods with `_` suffix will mod
 
 https://github.com/pocketpy/pocketpy/blob/main/include/typings/linalg.pyi
 
-:::code source="../../include/typings/linalg.pyi" :::
+```python
+from typing import overload
+from c import _StructLike, float_p
+
+class vec2:
+    x: float
+    y: float
+
+    def __init__(self, x: float, y: float) -> None: ...
+    def __add__(self, other: vec2) -> vec2: ...
+    def __sub__(self, other: vec2) -> vec2: ...
+    def __getitem__(self, index: int) -> float: ...
+
+    @overload
+    def __mul__(self, other: float) -> vec2: ...
+    @overload
+    def __mul__(self, other: vec2) -> vec2: ...
+
+    def __rmul__(self, other: float) -> vec2: ...
+    def __truediv__(self, other: float) -> vec2: ...
+    def dot(self, other: vec2) -> float: ...
+    def cross(self, other: vec2) -> float: ...
+    def length(self) -> float: ...
+    def length_squared(self) -> float: ...
+    def normalize(self) -> vec2: ...
+    def rotate(self, radians: float) -> vec2: ...
+
+    @staticmethod
+    def angle(__from: vec2, __to: vec2) -> float:
+        """Returns the angle in radians between vectors `from` and `to`.
+
+        The result range is `[-pi, pi]`.
+        
+        + if y axis is top to bottom, positive value means clockwise
+        + if y axis is bottom to top, positive value means counter-clockwise
+        """
+
+    @staticmethod
+    def smooth_damp(current: vec2, target: vec2, current_velocity: vec2, smooth_time: float, max_speed: float, delta_time: float) -> tuple[vec2, vec2]:
+        ...
+
+class vec3:
+    x: float
+    y: float
+    z: float
+
+    def __init__(self, x: float, y: float, z: float) -> None: ...
+    def __add__(self, other: vec3) -> vec3: ...
+    def __sub__(self, other: vec3) -> vec3: ...
+    def __getitem__(self, index: int) -> float: ...
+
+    @overload
+    def __mul__(self, other: float) -> vec3: ...
+    @overload
+    def __mul__(self, other: vec3) -> vec3: ...
+
+    def __rmul__(self, other: float) -> vec3: ...
+    def __truediv__(self, other: float) -> vec3: ...
+    def dot(self, other: vec3) -> float: ...
+    def cross(self, other: vec3) -> float: ...
+    def length(self) -> float: ...
+    def length_squared(self) -> float: ...
+    def normalize(self) -> vec3: ...
+
+class vec4(_StructLike['vec4']):
+    x: float
+    y: float
+    z: float
+    w: float
+
+    def __init__(self, x: float, y: float, z: float, w: float) -> None: ...
+    def __add__(self, other: vec4) -> vec4: ...
+    def __sub__(self, other: vec4) -> vec4: ...
+    def __getitem__(self, index: int) -> float: ...
+
+    @overload
+    def __mul__(self, other: float) -> vec4: ...
+    @overload
+    def __mul__(self, other: vec4) -> vec4: ...
+
+    def __rmul__(self, other: float) -> vec4: ...
+    def __truediv__(self, other: float) -> vec4: ...
+    def dot(self, other: vec4) -> float: ...
+    def length(self) -> float: ...
+    def length_squared(self) -> float: ...
+    def normalize(self) -> vec4: ...
+
+    def copy_(self, other: vec4) -> None: ...
+    def normalize_(self) -> None: ...
+
+class mat3x3(_StructLike['mat3x3']):
+    _11: float
+    _12: float
+    _13: float
+    _21: float
+    _22: float
+    _23: float
+    _31: float
+    _32: float
+    _33: float
+
+    @overload
+    def __init__(self) -> None: ...
+    @overload
+    def __init__(self, _11, _12, _13, _21, _22, _23, _31, _32, _33) -> None: ...
+    @overload
+    def __init__(self, a: list[float]): ...
+
+    def determinant(self) -> float: ...
+    def inverse(self) -> mat3x3: ...
+    def transpose(self) -> mat3x3: ...
+
+    def __getitem__(self, index: tuple[int, int]) -> float: ...
+    def __setitem__(self, index: tuple[int, int], value: float) -> None: ...
+    def __add__(self, other: mat3x3) -> mat3x3: ...
+    def __sub__(self, other: mat3x3) -> mat3x3: ...
+    def __mul__(self, other: float) -> mat3x3: ...
+    def __rmul__(self, other: float) -> mat3x3: ...
+    def __truediv__(self, other: float) -> mat3x3: ...
+
+    def __invert__(self) -> mat3x3: ...
+    @overload
+    def __matmul__(self, other: mat3x3) -> mat3x3: ...
+    @overload
+    def __matmul__(self, other: vec3) -> vec3: ...
+
+    def matmul(self, other: mat3x3, out: mat3x3 = None) -> mat3x3 | None: ...
+
+    def copy_(self, other: mat3x3) -> None: ...
+    def inverse_(self) -> None: ...
+    def transpose_(self) -> None: ...
+
+    @staticmethod
+    def zeros() -> mat3x3: ...
+    @staticmethod
+    def ones() -> mat3x3: ...
+    @staticmethod
+    def identity() -> mat3x3: ...
+
+    # affine transformations
+    @staticmethod
+    def trs(t: vec2, r: float, s: vec2) -> mat3x3: ...
+
+    def copy_trs_(self, t: vec2, r: float, s: vec2) -> None: ...
+    def copy_t_(self, t: vec2) -> None: ...
+    def copy_r_(self, r: float) -> None: ...
+    def copy_s_(self, s: vec2) -> None: ...
+
+    def _t(self) -> vec2: ...
+    def _r(self) -> float: ...
+    def _s(self) -> vec2: ...
+
+    def is_affine(self) -> bool: ...
+
+    def transform_point(self, p: vec2) -> vec2: ...
+    def transform_vector(self, v: vec2) -> vec2: ...
+    def inverse_transform_point(self, p: vec2) -> vec2: ...
+    def inverse_transform_vector(self, v: vec2) -> vec2: ...
+
+vec4_p = float_p
+mat3x3_p = float_p
+
+```

docs/modules/typing.md

@@ -4,5 +4,3 @@ label: typing
 ---
 
 Placeholder module for type hints.
-
-:::code source="../../python/typing.py" :::

include/pocketpy/pocketpy.h

@@ -34,7 +34,11 @@ typedef struct c11_sv {
     int size;
 } c11_sv;
 
+/// Mark a function that can raise an exception.
+/// + If the function returns `bool`, then `false` means an exception is raised.
+/// + If the function returns `int`, then `-1` means an exception is raised.
 #define PY_RAISE
+/// Mark a function that returns a value by `py_retval()` on success.
 #define PY_RETURN
 
 /// A generic reference to a python object.

scripts/gen_docs.py

@@ -1,68 +0,0 @@
-import re
-from dataclasses import dataclass
-
-NEWLINE = '\n'
-
-@dataclass
-class Function:
-    name: str
-    args: str
-    ret: str
-    comment: str
-    is_py_raise: bool
-    is_py_return: bool
-
-    def signature(self):
-        tmp = f"PK_EXPORT {self.ret} {self.name}{self.args}"
-        return tmp + ';'
-    
-    def badges(self):
-        res = []
-        if self.is_py_raise:
-            res.append('[!badge text="raise" variant="danger"](../introduction/#py_raise-macro)')
-        if self.is_py_return:
-            res.append('[!badge text="return"](../introduction/#py_return-macro)')
-        return ' '.join(res)
-
-    def markdown(self):
-        lines = [
-            f"### {self.name}" + f" {self.badges()}",
-            f"```c",
-            self.comment,
-            f"{self.signature()}",
-            f"```",
-        ]
-        return '\n'.join(lines)
-
-with open('include/pocketpy/pocketpy.h') as f:
-    header = f.read()
-
-matches = re.finditer(r"((?:/// [^\n]+[\n])*?)PK_EXPORT\s+(\w+)\s+(\w+)(\(.*?\))\s*(PY_RAISE)?\s*(PY_RETURN)?\s*;", header, re.DOTALL)
-#                       ^1 comment                        ^2 ret  ^3    ^4 args    ^5 py_raise?  ^6 py_return?
-
-functions: list[Function] = []
-for match in matches:
-    functions.append(Function(
-        name=match[3],
-        args=match[4],
-        ret=match[2],
-        comment=match[1].strip(),
-        is_py_raise=bool(match[5]),
-        is_py_return=bool(match[6])
-    ))
-    # print(functions[-1])
-
-
-# generate markdown
-with open('docs/C-API/functions.md', 'w', newline='\n') as f:
-    f.write('\n'.join([
-        '---',
-        'title: Functions',
-        'icon: dot',
-        'order: 0',
-        '---',
-        '\n\n',
-    ]))
-    for function in functions:
-        f.write(function.markdown())
-        f.write('\n\n')