From 122291b24be1df76a14f155b944fe7088758583b Mon Sep 17 00:00:00 2001
From: ashawkey <ashawkey1999@gmail.com>
Date: Fri, 22 Mar 2024 14:38:09 +0800
Subject: [PATCH] 0.2.6: better doc

---
 docs/readme.md         | 19 +++++++++++++++++++
 docs/source/blender.md | 10 +++++-----
 docs/source/camera.md  | 11 +++++++----
 docs/source/conf.py    |  2 +-
 docs/source/mesh.md    |  2 +-
 kiui/cam.py            |  2 +-
 kiui/mesh_utils.py     |  2 +-
 setup.py               |  2 +-
 8 files changed, 36 insertions(+), 14 deletions(-)
 create mode 100644 docs/readme.md

diff --git a/docs/readme.md b/docs/readme.md
new file mode 100644
index 0000000..b2bc873
--- /dev/null
+++ b/docs/readme.md
@@ -0,0 +1,19 @@
+# Docs for kiuikit
+
+We use [sphinx](https://www.sphinx-doc.org/en/master/) and [m2r2](https://github.com/CrossNox/m2r2) to build the documentation in markdown language.
+
+### Usage
+
+Since sphinx needs to import the module for auto-doc, we need to install full dependency first:
+```bash
+pip install -e ".[full]"
+pip install -r docs/requirements.txt
+```
+
+Build the docs by:
+```bash
+cd docs
+make html
+```
+
+View the local [html](docs/build/html/index.html) by VSCode `Live Server` extension.
\ No newline at end of file
diff --git a/docs/source/blender.md b/docs/source/blender.md
index 5330484..1b21b5b 100644
--- a/docs/source/blender.md
+++ b/docs/source/blender.md
@@ -1,22 +1,22 @@
-# Blender
+# Blender Scripts
 
 To render complex 3D models (specifically with multiple submeshes), the only choice is to use `blender` and `bpy`.
 
 We provide an example code for rendering with blender:
 
 ```bash
-# make sure you are using python 3.10
+# make sure you are using python>=3.10, tested with bpy==4.0.0
 pip install bpy mathutils
 
 # help
 python -m kiui.cli.blender_render --help
 
 # example
-python -m kiui.cli.blender_render --mesh chest.glb --gpu 0 --depth --normal --albedo
+python -m kiui.cli.blender_render --mesh chest.glb --gpu 0 --depth --normal --albedo --camera --blend
 ```
 
 Features include:
 * Set which GPU to use with `--gpu 0` for `CYCLES` rendering engine.
-* Render with random HDRI environment texture shading (check `assets/blender_lights`).
-* Render depth (`exr`), normal, and albedo.
+* Render with random built-in HDRI environment texture shading (check `assets/blender_lights`).
+* Optionally render depth (`exr`), normal, and albedo.
 * Empirical cleaning of the scene (remove the annoying plane under the object).
\ No newline at end of file
diff --git a/docs/source/camera.md b/docs/source/camera.md
index cc2b1f4..ebc74bb 100644
--- a/docs/source/camera.md
+++ b/docs/source/camera.md
@@ -1,6 +1,6 @@
 # Camera
 
-### Common world coordinate systems
+### World coordinate systems
 ```
 OpenGL/MAYA       OpenCV/Colmap     Blender      Unity/DirectX     Unreal   
 Right-handed      Right-handed    Right-handed    Left-handed    Left-handed
@@ -20,7 +20,9 @@ A common color code: x = <span style="color:red">red</span>, y = <span style="co
 > **Left/right-handed notation**: roll your left/right palm from x to y, and your thumb should point to z.
 
 
-### Camera pose matrix
+### Camera pose coordinate systems
+
+A Camera pose matrix (camera to world transformation) is in the form of:
 ```
 [[Right_x, Up_x, Forward_x, Position_x],
  [Right_y, Up_y, Forward_y, Position_y],
@@ -34,7 +36,7 @@ However, the three directions (right, up, forward) can be defined differently:
 * up can align with the world-up-axis (`y`) or world-down-axis (`-y`).
 * right can also be left, depending on it's (`up cross forward`) or (`forward cross up`).
 
-### Common camera coordinate systems
+This leads to two common camera conventions:
 ```
    OpenGL                OpenCV       
    Blender               Colmap       
@@ -59,7 +61,8 @@ A common color code: right = <span style="color:red">red</span>., up = <span sty
 
 ### API
 
-**Note that the camera API is designed to be `numpy` based and un-batched!**
+.. note::
+   the camera API is designed to be `numpy` based and un-batched!
 
 .. automodule:: kiui.cam
    :members:
\ No newline at end of file
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 9e8dcd5..2eef638 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -21,7 +21,7 @@
 author = 'kiui'
 
 # The full version, including alpha/beta/rc tags
-release = '0.2.5'
+release = '0.2.6'
 
 
 # -- General configuration ---------------------------------------------------
diff --git a/docs/source/mesh.md b/docs/source/mesh.md
index f4a935b..a5fdd37 100644
--- a/docs/source/mesh.md
+++ b/docs/source/mesh.md
@@ -1,6 +1,6 @@
 # Mesh
 
-`kiui.mesh.Mesh` class provides an implementation of a triangular mesh in PyTorch.
+`kiui.mesh.Mesh` class provides an implementation of triangle meshes in PyTorch.
 
 `kiui.mesh_utils` provides utility functions for mesh processing and loss functions.
 
diff --git a/kiui/cam.py b/kiui/cam.py
index 5645168..75fea52 100644
--- a/kiui/cam.py
+++ b/kiui/cam.py
@@ -57,7 +57,7 @@ def convert(
 
 
 def look_at(campos, target, opengl=True):
-    """construct pose rotation matrix by look-at
+    """construct pose rotation matrix by look-at.
 
     Args:
         campos (np.ndarray): camera position, float [3]
diff --git a/kiui/mesh_utils.py b/kiui/mesh_utils.py
index e637662..b2657e7 100644
--- a/kiui/mesh_utils.py
+++ b/kiui/mesh_utils.py
@@ -34,7 +34,7 @@ def decimate_mesh(
 ):
     """ perform mesh decimation.
 
-    Args:pml
+    Args:
         verts (np.ndarray): mesh vertices, float [N, 3]
         faces (np.ndarray): mesh faces, int [M, 3]
         target (int): targeted number of faces
diff --git a/setup.py b/setup.py
index d7ee02b..c4b5938 100644
--- a/setup.py
+++ b/setup.py
@@ -3,7 +3,7 @@
 if __name__ == "__main__":
     setup(
         name="kiui",
-        version="0.2.5",
+        version="0.2.6",
         description="A toolkit for 3D vision",
         long_description=open("README.md", encoding="utf-8").read(),
         long_description_content_type="text/markdown",