docs: use sphinx_rtd_theme theme dor documentation

docs/source/build.rst

@@ -1,9 +1,7 @@
-Building cglm
+Build cglm
 ================================
 
-| **cglm** does not have external dependencies except for unit testing.
+| **cglm** does not have external dependencies except for unit testing. When you pulled **cglm** repo with submodules all dependencies will be pulled too. `build-deps.sh` will pull all dependencies/submodules and build for you.
-| When you pulled cglm repo with submodules all dependencies will be pulled too.
-| `build-deps.sh` will pull all dependencies/submodules and build for you.
 
 External dependencies:
   * cmocka - for unit testing
@@ -12,7 +10,8 @@ External dependencies:
 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
 
-**Unix (Autotools):**
+Unix (Autotools):
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. code-block:: bash
   :linenos:
@@ -26,11 +25,12 @@ Just import cglm to your project as dependency / external lib by copy-paste then
   $ [sudo] make install   # install to system (optional)
 
 **make** will build cglm to **.libs** sub folder in project folder.
-If you don't want to install cglm to your system's folder you can get static and dynamic libs in this folder.
+If you don't want to install **cglm** to your system's folder you can get static and dynamic libs in this folder.
 
-**Build dependencies (windows):**
+Windows (MSBuild):
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Windows related build files, project files are located in win folder,
+Windows related build files, project files are located in `win` folder,
 make sure you are inside in cglm/win folder.
 
 Code Analysis are enabled, it may take awhile to build.
@@ -50,3 +50,19 @@ then try to build with *devenv*:
   $ devenv cglm.sln /Build Release
 
 Currently tests are not available on Windows.
+
+Documentation (Sphinx):
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**cglm** uses sphinx framework for documentation, it allows lot of formats for documentation. To see all options see sphinx build page:
+
+https://www.sphinx-doc.org/en/master/man/sphinx-build.html
+
+Example build:
+
+.. code-block:: bash
+  :linenos:
+
+  $ cd cglm/docs
+  $ sphinx-build source build
+

docs/source/conf.py

@@ -90,7 +90,7 @@ todo_include_todos = False
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+html_theme = 'sphinx_rtd_theme'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -99,13 +99,13 @@ html_theme = 'alabaster'
 # html_theme_options = {}
 
 html_theme_options = {
-    'github_banner': 'true',
+    # 'github_banner': 'true',
-    'github_button': 'true',
+    # 'github_button': 'true',
-    'github_user': 'recp',
+    # 'github_user': 'recp',
-    'github_repo': 'cglm',
+    # 'github_repo': 'cglm',
-    'travis_button': 'true',
+    # 'travis_button': 'true',
-    'show_related': 'true',
+    # 'show_related': 'true',
-    'fixed_sidebar': 'true'
+    # 'fixed_sidebar': 'true'
 }
 
 # Add any paths that contain custom static files (such as style sheets) here,

docs/source/features.rst

@@ -0,0 +1,23 @@
+Features
+================================================================================
+
+* general purpose matrix operations (mat4, mat3)
+* chain matrix multiplication (square only)
+* general purpose vector operations (cross, dot, rotate, proj, angle...)
+* affine transforms
+* matrix decomposition (extract rotation, scaling factor)
+* optimized affine transform matrices (mul, rigid-body inverse)
+* camera (lookat)
+* projections (ortho, perspective)
+* quaternions
+* euler angles / yaw-pitch-roll to matrix
+* extract euler angles
+* inline or pre-compiled function call
+* frustum (extract view frustum planes, corners...)
+* bounding box (AABB in Frustum (culling), crop, merge...)
+* bounding sphere
+* project, unproject
+* easing functions
+* curves
+* curve interpolation helpers (SMC, deCasteljau...)
+* and other...

docs/source/getting_started.rst

@@ -9,23 +9,26 @@ Types:
 .. code-block:: c
   :linenos:
 
+  typedef float                   vec2[2];
   typedef float                   vec3[3];
   typedef int                    ivec3[3];
-   typedef CGLM_ALIGN(16) float vec4[4];
+  typedef CGLM_ALIGN_IF(16) float vec4[4];
-
-   typedef vec3 mat3[3];
-   typedef vec4 mat4[4];
-
   typedef vec4                    versor;
+  typedef vec3                    mat3[3];
+
+  #ifdef __AVX__
+  typedef CGLM_ALIGN_IF(32) vec4  mat4[4];
+  #else
+  typedef CGLM_ALIGN_IF(16) vec4  mat4[4];
+  #endif
 
 As you can see types don't store extra informations in favor of space.
 You can send these values e.g. matrix to OpenGL directly without casting or calling a function like *value_ptr*
 
-Alignment is Required:
+Alignment Is Required:
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-**vec4** and **mat4** requires 16 byte alignment because vec4 and mat4 operations are
+**vec4** and **mat4** requires 16 (32 for **mat4** if AVX is enabled) byte alignment because **vec4** and **mat4** operations are vectorized by SIMD instructions (SSE/AVX/NEON).
-vectorized by SIMD instructions (SSE/AVX).
 
 **UPDATE:**
   By starting v0.4.5 cglm provides an option to disable alignment requirement, it is enabled as default
@@ -37,10 +40,9 @@ vectorized by SIMD instructions (SSE/AVX).
 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.
+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.
-When allocating memory don't forget that **vec4** and **mat4** requires alignment.
 
-**NOTE:** Unaligned vec4 and unaligned mat4 operations will be supported in the future. Check todo list.
+**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**
 

docs/source/index.rst

@@ -3,7 +3,7 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to cglm's documentation!
+cglm Documentation
 ================================
 
 **cglm** is optimized 3D math library written in C99 (compatible with C89).
@@ -14,33 +14,36 @@ is considered to be supported as optional.
 
 Also currently only **float** type is supported for most operations.
 
-**Features**
-
-* general purpose matrix operations (mat4, mat3)
-* chain matrix multiplication (square only)
-* general purpose vector operations (cross, dot, rotate, proj, angle...)
-* affine transforms
-* matrix decomposition (extract rotation, scaling factor)
-* optimized affine transform matrices (mul, rigid-body inverse)
-* camera (lookat)
-* projections (ortho, perspective)
-* quaternions
-* euler angles / yaw-pitch-roll to matrix
-* extract euler angles
-* inline or pre-compiled function call
-* frustum (extract view frustum planes, corners...)
-* bounding box (AABB in Frustum (culling), crop, merge...)
-
-
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
-   :caption: Table Of Contents:
+   :caption: Getting Started:
 
+   features
    build
    getting_started
+
+.. toctree::
+   :maxdepth: 2
+   :caption: How To:
+
    opengl
+
+.. toctree::
+   :maxdepth: 2
+   :caption: API:
+
    api
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Options:
+
    opt
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Troubleshooting:
+
    troubleshooting
 
 Indices and tables

docs/source/opengl.rst

@@ -45,7 +45,7 @@ array of matrices:
 
 in this way, passing aray of matrices is same
 
-Passing / Uniforming Vectors to OpenGL:¶
+Passing / Uniforming Vectors to OpenGL:
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 You don't need to do extra thing when passing cglm vectors to OpengL or other APIs.