Merge pull request #390 from waywardmonkeys/doc-improvements

Doc improvements

.github/workflows/ci.yml

@@ -173,7 +173,7 @@ jobs:
 
     - name: Build
       working-directory: docs
-      run: sphinx-build source build
+      run: sphinx-build -W --keep-going source build
 
   build_meson:
     name: Meson / ${{ matrix.os }}

docs/source/affine-pre.rst

@@ -78,49 +78,6 @@ Functions documentation
       | *[in, out]* **m**  affine transform
       | *[in]*      **v**  z factor
 
-.. c:function:: void  glm_translate_make(mat4 m, vec3 v)
-
-    creates NEW translate transform matrix by *v* vector.
-
-    Parameters:
-      | *[in, out]* **m**  affine transform
-      | *[in]*      **v**  translate vector [x, y, z]
-
-.. c:function:: void  glm_scale_to(mat4 m, vec3 v, mat4 dest)
-
-    scale existing transform matrix by *v* vector and store result in dest
-
-    Parameters:
-      | *[in]*  **m**    affine transform
-      | *[in]*  **v**    scale vector [x, y, z]
-      | *[out]* **dest** scaled matrix
-
-.. c:function:: void  glm_scale_make(mat4 m, vec3 v)
-
-    creates NEW scale matrix by v vector
-
-    Parameters:
-      | *[out]* **m** affine transform
-      | *[in]*  **v** scale vector [x, y, z]
-
-.. c:function:: void  glm_scale(mat4 m, vec3 v)
-
-    scales existing transform matrix by v vector
-    and stores result in same matrix
-
-    Parameters:
-      | *[in, out]* **m** affine transform
-      | *[in]*      **v** scale vector [x, y, z]
-
-.. c:function:: void  glm_scale_uni(mat4 m, float s)
-
-    applies uniform scale to existing transform matrix v = [s, s, s]
-    and stores result in same matrix
-
-    Parameters:
-      | *[in, out]* **m** affine transform
-      | *[in]*      **v** scale factor
-
 .. c:function:: void  glm_rotate_x(mat4 m, float angle, mat4 dest)
 
     rotate existing transform matrix around X axis by angle
@@ -151,16 +108,6 @@ Functions documentation
       | *[in]*  **angle** angle (radians)
       | *[out]* **dest**  rotated matrix
 
-.. c:function:: void  glm_rotate_make(mat4 m, float angle, vec3 axis)
-
-    creates NEW rotation matrix by angle and axis,
-    axis will be normalized so you don't need to normalize it
-
-    Parameters:
-      | *[out]* **m**    affine transform
-      | *[in]*  **axis** angle (radians)
-      | *[in]*  **axis** axis
-
 .. c:function:: void  glm_rotate(mat4 m, float angle, vec3 axis)
 
     rotate existing transform matrix around Z axis by angle and axis
@@ -180,56 +127,6 @@ Functions documentation
       | *[in]*      **angle** angle (radians)
       | *[in]*      **axis**  axis
 
-.. c:function:: void  glm_rotate_atm(mat4 m, vec3 pivot, float angle, vec3 axis)
-
-    | creates NEW rotation matrix by angle and axis at given point
-    | this creates rotation matrix, it assumes you don't have a matrix
-
-    | this should work faster than glm_rotate_at because it reduces one glm_translate.
-
-    Parameters:
-      | *[in, out]* **m**     affine transform
-      | *[in]*      **pivot** pivot, anchor point, rotation center
-      | *[in]*      **angle** angle (radians)
-      | *[in]*      **axis**  axis
-
-.. c:function:: void  glm_decompose_scalev(mat4 m, vec3 s)
-
-    decompose scale vector
-
-    Parameters:
-      | *[in]*  **m**  affine transform
-      | *[out]* **s**  scale vector (Sx, Sy, Sz)
-
-.. c:function:: bool  glm_uniscaled(mat4 m)
-
-    returns true if matrix is uniform scaled.
-    This is helpful for creating normal matrix.
-
-    Parameters:
-      | *[in]*  **m**   matrix
-
-.. c:function:: void  glm_decompose_rs(mat4 m, mat4 r, vec3 s)
-
-    decompose rotation matrix (mat4) and scale vector [Sx, Sy, Sz]
-    DON'T pass projected matrix here
-
-    Parameters:
-      | *[in]*  **m** affine transform
-      | *[out]* **r** rotation matrix
-      | *[out]* **s** scale matrix
-
-.. c:function:: void  glm_decompose(mat4 m, vec4 t, mat4 r, vec3 s)
-
-    decompose affine transform, TODO: extract shear factors.
-    DON'T pass projected matrix here
-
-    Parameters:
-      | *[in]*  **m** affine transform
-      | *[out]* **t** translation vector
-      | *[out]* **r** rotation matrix (mat4)
-      | *[out]* **s** scaling vector [X, Y, Z]
-
 .. c:function:: void  glm_spin(mat4 m, float angle, vec3 axis)
 
     | rotate existing transform matrix around given axis by angle around self (doesn't affected by position)

docs/source/api_inline_array.rst

@@ -9,7 +9,7 @@ In the future there may be option to forward struct api to call api instead of i
 
 📌 **USE this API docs for similar functions in struct and call api** 
 
-📌 In struct api you can omit namespace e.g :code:`glms_vec3_dot` can be called as :code:`vec3_dot` in struct api, see :doc:`struct-api` to configure struct api for more details. 
+📌 In struct api you can omit namespace e.g :code:`glms_vec3_dot` can be called as :code:`vec3_dot` in struct api, see :doc:`api_struct` to configure struct api for more details.
 📌 In struct api functions can return struct/union
 📌 In struct api you can access items like **.x**, **.y**, **.z**, **.w**, **.r**, **.g**, **.b**, **.a**, **.m00**, **m01**... 
 
@@ -43,6 +43,7 @@ Follow the :doc:`build` documentation for this
    cam
    frustum
    box
+   aabb2d
    quat
    euler
    mat2

docs/source/build.rst

@@ -3,9 +3,9 @@ Build cglm
 
 | **cglm** does not have any external dependencies.
 
-**NOTE:**
-If you only need to inline versions, you don't need to build **cglm**, you don't need to link it to your program.
-Just import cglm to your project as dependency / external lib by copy-paste then use it as usual
+.. note::
+   If you only need to inline versions, you don't need to build **cglm**, you don't need to link it to your program.
+   Just import cglm to your project as dependency / external lib by copy-paste then use it as usual
 
 CMake (All platforms):
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

docs/source/cam.rst

@@ -18,10 +18,10 @@ fast if you don't care specific projection values.
 *_decomp* means decompose; these function can help to decompose projection
 matrices.
 
- **NOTE**: Be careful when working with high range (very small near, very large
- far) projection matrices. You may not get exact value you gave.
- **float** type cannot store very high precision so you will lose precision.
- Also your projection matrix will be inaccurate due to losing precision
+.. note:: Be careful when working with high range (very small near, very large
+   far) projection matrices. You may not get exact value you gave.
+   **float** type cannot store very high precision so you will lose precision.
+   Also your projection matrix will be inaccurate due to losing precision
 
 Table of contents (click to go):
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -178,7 +178,7 @@ Functions documentation
 
     | set up view matrix
 
-    **NOTE:** The UP vector must not be parallel to the line of sight from the eye point to the reference point.
+    .. note:: The UP vector must not be parallel to the line of sight from the eye point to the reference point.
 
     Parameters:
       | *[in]*  **eye**     eye vector
@@ -194,7 +194,7 @@ Functions documentation
     target self then this might be useful. Because you need to get target
     from direction.
 
-    **NOTE:** The UP vector must not be parallel to the line of sight from the eye point to the reference point.
+    .. note:: The UP vector must not be parallel to the line of sight from the eye point to the reference point.
 
     Parameters:
       | *[in]*  **eye**     eye vector

docs/source/getting_started.rst

@@ -42,9 +42,9 @@ Allocations:
 *cglm* doesn't alloc any memory on heap. So it doesn't provide any allocator.
 You must allocate memory yourself. You should alloc memory for out parameters too if you pass pointer of memory location. When allocating memory, don't forget that **vec4** and **mat4** require alignment.
 
-**NOTE:** Unaligned **vec4** and unaligned **mat4** operations will be supported in the future. Check todo list.
-Because you may want to multiply a CGLM matrix with external matrix.
-There is no guarantee that non-CGLM matrix is aligned. Unaligned types will have *u* prefix e.g. **umat4**
+.. note:: Unaligned **vec4** and unaligned **mat4** operations will be supported in the future. Check todo list.
+   Because you may want to multiply a CGLM matrix with external matrix.
+   There is no guarantee that non-CGLM matrix is aligned. Unaligned types will have *u* prefix e.g. **umat4**
 
 Array vs Struct:
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

docs/source/io.rst

@@ -24,9 +24,9 @@ Example to print mat4 matrix:
    /* ... */
    glm_mat4_print(transform, stderr);
 
-**NOTE:** print functions use **%0.4f** precision if you need more
-(you probably will in some cases), you can change it temporary.
-cglm may provide precision parameter in the future
+.. note:: print functions use **%0.4f** precision if you need more
+   (you probably will in some cases), you can change it temporary.
+   cglm may provide precision parameter in the future.
 
 Changes since **v0.7.3**:
 * Now mis-alignment of columns are fixed: larger numbers are printed via %g and others are printed via %f. Column widths are calculated before print.

docs/source/mat2.rst

@@ -184,7 +184,7 @@ Functions documentation
 
     Create mat2 matrix from pointer
 
-    | NOTE: **@src** must contain at least 4 elements.
+    .. note:: **@src** must contain at least 4 elements.
 
     Parameters:
       | *[in]*  **src**  pointer to an array of floats

docs/source/mat2x3.rst

@@ -45,7 +45,7 @@ Functions documentation
 
     Create mat2x3 matrix from pointer
 
-    | NOTE: **@src** must contain at least 6 elements.
+    .. note:: **@src** must contain at least 6 elements.
 
     Parameters:
       | *[in]*  **src**  pointer to an array of floats

docs/source/mat2x4.rst

@@ -45,7 +45,7 @@ Functions documentation
 
     Create mat2x4 matrix from pointer
 
-    | NOTE: **@src** must contain at least 8 elements.
+    .. note:: **@src** must contain at least 8 elements.
 
     Parameters:
       | *[in]*  **src**  pointer to an array of floats

docs/source/mat3.rst

@@ -194,7 +194,7 @@ Functions documentation
 
     Create mat3 matrix from pointer
 
-    | NOTE: **@src** must contain at least 9 elements.
+    .. note:: **@src** must contain at least 9 elements.
 
     Parameters:
       | *[in]*  **src**  pointer to an array of floats

docs/source/mat3x2.rst

@@ -45,7 +45,8 @@ Functions documentation
 
     Create mat3x2 matrix from pointer
 
-    | NOTE: **@src** must contain at least 6 elements.
+    .. note:: **@src** must contain at least 6 elements.
+
     Parameters:
       | *[in]*  **src**  pointer to an array of floats
       | *[out]* **dest** destination matrix3x2

docs/source/mat3x4.rst

@@ -45,7 +45,8 @@ Functions documentation
 
     Create mat3x4 matrix from pointer
 
-    | NOTE: **@src** must contain at least 12 elements.
+    .. note::: **@src** must contain at least 12 elements.
+
     Parameters:
       | *[in]*  **src**  pointer to an array of floats
       | *[out]* **dest** destination matrix3x4

docs/source/mat4.rst

@@ -34,8 +34,8 @@ Functions:
 #. :c:func:`glm_mat4_mulN`
 #. :c:func:`glm_mat4_mulv`
 #. :c:func:`glm_mat4_mulv3`
-#. :c:func:`glm_mat3_trace`
-#. :c:func:`glm_mat3_trace3`
+#. :c:func:`glm_mat4_trace`
+#. :c:func:`glm_mat4_trace3`
 #. :c:func:`glm_mat4_quat`
 #. :c:func:`glm_mat4_transpose_to`
 #. :c:func:`glm_mat4_transpose`
@@ -263,7 +263,7 @@ Functions documentation
     | e.g Newton-Raphson. this should work faster than normal,
     | to get more precise use glm_mat4_inv version.
 
-    | NOTE: You will lose precision, glm_mat4_inv is more accurate
+    .. note:: You will lose precision, glm_mat4_inv is more accurate
 
     Parameters:
       | *[in]*  **mat**   source
@@ -308,7 +308,7 @@ Functions documentation
 
     Create mat4 matrix from pointer
 
-    | NOTE: **@src** must contain at least 16 elements.
+    .. note:: **@src** must contain at least 16 elements.
 
     Parameters:
       | *[in]*  **src**  pointer to an array of floats

docs/source/mat4x2.rst

@@ -45,7 +45,8 @@ Functions documentation
 
     Create mat4x2 matrix from pointer
 
-    | NOTE: **@src** must contain at least 8 elements.
+    .. note:: **@src** must contain at least 8 elements.
+
     Parameters:
       | *[in]*  **src**  pointer to an array of floats
       | *[out]* **dest** destination matrix4x2

docs/source/mat4x3.rst

@@ -45,7 +45,8 @@ Functions documentation
 
     Create mat4x3 matrix from pointer
 
-    | NOTE: **@src** must contain at least 12 elements.
+    .. note:: **@src** must contain at least 12 elements.
+
     Parameters:
       | *[in]*  **src**  pointer to an array of floats
       | *[out]* **dest** destination matrix4x3

docs/source/quat.rst

@@ -426,7 +426,7 @@ Functions documentation
 
     Create quaternion from pointer
 
-    | NOTE: **@src** must contain at least 4 elements. cglm store quaternions as [x, y, z, w].
+    .. note:: **@src** must contain at least 4 elements. cglm store quaternions as [x, y, z, w].
 
     Parameters:
       | *[in]*  **src**  pointer to an array of floats

docs/source/vec2.rst

@@ -389,7 +389,8 @@ Functions documentation
 
     Create two dimensional vector from pointer
 
-    | NOTE: **@src** must contain at least 2 elements.
+    .. note:: **@src** must contain at least 2 elements.
+
     Parameters:
       | *[in]*  **src**  pointer to an array of floats
       | *[out]* **dest** destination vector

docs/source/vec3.rst

@@ -507,7 +507,7 @@ Functions documentation
 
     Create three dimensional vector from pointer
 
-    | NOTE: **@src** must contain at least 3 elements.
+    .. note::: **@src** must contain at least 3 elements.
 
     Parameters:
       | *[in]*  **src**  pointer to an array of floats

docs/source/vec4.rst

@@ -108,6 +108,13 @@ Functions documentation
     Parameters:
       | *[in, out]*  **v**     vector
 
+.. c:function:: void  glm_vec4_one(vec4 v)
+
+    makes all members one
+
+    Parameters:
+      | *[in, out]*  **v**     vector
+
 .. c:function:: float  glm_vec4_dot(vec4 a, vec4 b)
 
     dot product of vec4
@@ -412,7 +419,8 @@ Functions documentation
 
     Create four dimensional vector from pointer
 
-    | NOTE: **@src** must contain at least 4 elements.
+    .. note:: **@src** must contain at least 4 elements.
+
     Parameters:
       | *[in]*  **src**  pointer to an array of floats
       | *[out]* **dest** destination vector