From af5048595ffb12184cdb90ed4ce688773edf070b Mon Sep 17 00:00:00 2001 From: Bruce Mitchener Date: Sun, 11 Feb 2024 23:39:03 +0700 Subject: [PATCH] docs: Use `.. note::` to display better. Also, make sure the note content has a blank line after it to remove a warning from Sphinx. --- docs/source/build.rst | 6 +++--- docs/source/cam.rst | 12 ++++++------ docs/source/getting_started.rst | 6 +++--- docs/source/io.rst | 6 +++--- docs/source/mat2.rst | 2 +- docs/source/mat2x3.rst | 2 +- docs/source/mat2x4.rst | 2 +- docs/source/mat3.rst | 2 +- docs/source/mat3x2.rst | 3 ++- docs/source/mat3x4.rst | 3 ++- docs/source/mat4.rst | 4 ++-- docs/source/mat4x2.rst | 3 ++- docs/source/mat4x3.rst | 3 ++- docs/source/quat.rst | 2 +- docs/source/vec2.rst | 3 ++- docs/source/vec3.rst | 2 +- docs/source/vec4.rst | 3 ++- 17 files changed, 35 insertions(+), 29 deletions(-) diff --git a/docs/source/build.rst b/docs/source/build.rst index e2eb23d..ad09a04 100644 --- a/docs/source/build.rst +++ b/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): ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/source/cam.rst b/docs/source/cam.rst index ca8716b..29e9b02 100644 --- a/docs/source/cam.rst +++ b/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 diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst index f764720..143b192 100644 --- a/docs/source/getting_started.rst +++ b/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: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/source/io.rst b/docs/source/io.rst index 5fad5b1..3b82380 100644 --- a/docs/source/io.rst +++ b/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. diff --git a/docs/source/mat2.rst b/docs/source/mat2.rst index e532e79..0be19f8 100644 --- a/docs/source/mat2.rst +++ b/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 diff --git a/docs/source/mat2x3.rst b/docs/source/mat2x3.rst index 84828c8..d3e735b 100644 --- a/docs/source/mat2x3.rst +++ b/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 diff --git a/docs/source/mat2x4.rst b/docs/source/mat2x4.rst index 0311084..9c97be3 100644 --- a/docs/source/mat2x4.rst +++ b/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 diff --git a/docs/source/mat3.rst b/docs/source/mat3.rst index 646c905..f294cf8 100644 --- a/docs/source/mat3.rst +++ b/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 diff --git a/docs/source/mat3x2.rst b/docs/source/mat3x2.rst index c3e2c21..9920e17 100644 --- a/docs/source/mat3x2.rst +++ b/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 diff --git a/docs/source/mat3x4.rst b/docs/source/mat3x4.rst index 042c030..6221136 100644 --- a/docs/source/mat3x4.rst +++ b/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 diff --git a/docs/source/mat4.rst b/docs/source/mat4.rst index bab45a8..bb0916e 100644 --- a/docs/source/mat4.rst +++ b/docs/source/mat4.rst @@ -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 diff --git a/docs/source/mat4x2.rst b/docs/source/mat4x2.rst index f4c71d2..3d605eb 100644 --- a/docs/source/mat4x2.rst +++ b/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 diff --git a/docs/source/mat4x3.rst b/docs/source/mat4x3.rst index 84c9196..0641a19 100644 --- a/docs/source/mat4x3.rst +++ b/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 diff --git a/docs/source/quat.rst b/docs/source/quat.rst index 186fe83..deb2e86 100644 --- a/docs/source/quat.rst +++ b/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 diff --git a/docs/source/vec2.rst b/docs/source/vec2.rst index 928471c..e299799 100644 --- a/docs/source/vec2.rst +++ b/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 diff --git a/docs/source/vec3.rst b/docs/source/vec3.rst index 892b66b..69fe52c 100644 --- a/docs/source/vec3.rst +++ b/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 diff --git a/docs/source/vec4.rst b/docs/source/vec4.rst index 2b7da9e..6a5f609 100644 --- a/docs/source/vec4.rst +++ b/docs/source/vec4.rst @@ -412,7 +412,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