Documentation Tree view overhaul + various fixes in doxygen

jfalcou · Dec 18, 2023 · 23db0f2 · 23db0f2
1 parent 5abea74
commit 23db0f2
Show file tree

Hide file tree

Showing 124 changed files with 461 additions and 601 deletions.
diff --git a/doc/Doxyfile b/doc/Doxyfile
@@ -535,7 +535,8 @@ RECURSIVE              = YES
 
 EXCLUDE                =  ../include/eve/detail/function/tmp  \
                           ../include/eve/module/real/         \
-                          ../include/eve/detail/
+                          ../include/eve/detail/              \
+                          ../include/eve/module/algo/algo/array_utils.hpp
 
 # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
 # directories that are symbolic links (a Unix file system feature) are excluded
@@ -877,22 +878,6 @@ TREEVIEW_WIDTH         = 250
 
 EXT_LINKS_IN_WINDOW    = NO
 FORMULA_FONTSIZE       = 10
-
-# Use the FORMULA_TRANSPARENT tag to determine whether or not the images
-# generated for formulas are transparent PNGs. Transparent PNGs are not
-# supported properly for IE 6.0, but are supported on all modern browsers.
-#
-# Note that when changing this option you need to delete any form_*.png files in
-# the HTML output directory before the changes have effect.
-# The default value is: YES.
-# This tag requires that the tag GENERATE_HTML is set to YES.
-
-FORMULA_TRANSPARENT    = YES
-
-# The FORMULA_MACROFILE can contain LaTeX \newcommand and \renewcommand commands
-# to create new LaTeX commands to be used in formulas as building blocks. See
-# the section "Including formulas" for details.
-
 FORMULA_MACROFILE      =
 
 # Enable the USE_MATHJAX option to render LaTeX formulas using MathJax (see

diff --git a/doc/page10_changelog.md → doc/changelog.md b/doc/page10_changelog.md → doc/changelog.md
diff --git a/doc/layout.xml b/doc/layout.xml
@@ -3,39 +3,98 @@
   <!-- Navigation index tabs for HTML output -->
   <navindex>
     <tab type="mainpage" visible="yes" title=""/>
-    <tab type="pages" visible="yes" title="" intro=""/>
-    <tab type="modules" visible="yes" title="" intro=""/>
-    <tab type="namespaces" visible="yes" title="">
-      <tab type="namespacelist" visible="yes" title="" intro=""/>
-      <tab type="namespacemembers" visible="yes" title="" intro=""/>
+    <tab type="usergroup" visible="yes" title="Tutorials">
+      <tab type="user" url="@ref setup"     title="Quick-Start"/>
+      <tab type="usergroup" visible="yes" title="SIMD 101">
+        <tab type="user" url="@ref intro-01" title="Basic Operations"/>
+        <tab type="user" url="@ref intro-02" title="Algorithms"/>
+        <tab type="user" url="@ref intro-03" title="Tuples"/>
+        <tab type="user" url="@ref intro-04" title="Data Structures"/>
+      </tab>
+      <tab type="usergroup" visible="yes" title="Specific Idioms">
+        <tab type="user" url="@ref conditional" title="Conditional Operations"/>
+        <tab type="user" url="@ref freqscale" title="Frequency Scaling"/>
+      </tab>
+      <tab type="usergroup" visible="yes" title="Advanced Topics">
+        <tab type="user" url="@ref inter-with-native" title="Interaction with native code"/>
+        <tab type="user" url="@ref multiarch" title="Handling Multiple Architecture Targets"/>
+      </tab>
     </tab>
-    <tab type="concepts" visible="yes" title="">
-    </tab>
-    <tab type="interfaces" visible="yes" title="">
-      <tab type="interfacelist" visible="yes" title="" intro=""/>
-      <tab type="interfaceindex" visible="$ALPHABETICAL_INDEX" title=""/>
-      <tab type="interfacehierarchy" visible="yes" title="" intro=""/>
-    </tab>
-    <tab type="classes" visible="yes" title="">
-      <tab type="classlist" visible="yes" title="" intro=""/>
-      <tab type="classindex" visible="$ALPHABETICAL_INDEX" title=""/>
-      <tab type="hierarchy" visible="yes" title="" intro=""/>
-      <tab type="classmembers" visible="yes" title="" intro=""/>
-    </tab>
-    <tab type="structs" visible="yes" title="">
-      <tab type="structlist" visible="yes" title="" intro=""/>
-      <tab type="structindex" visible="$ALPHABETICAL_INDEX" title=""/>
-    </tab>
-    <tab type="exceptions" visible="yes" title="">
-      <tab type="exceptionlist" visible="yes" title="" intro=""/>
-      <tab type="exceptionindex" visible="$ALPHABETICAL_INDEX" title=""/>
-      <tab type="exceptionhierarchy" visible="yes" title="" intro=""/>
+
+    <tab type="usergroup" visible="yes" title="Reference Documentation">
+      <tab type="user" url="@ref eve"     title="EVE Namespace"/>
+      <tab type="usergroup" visible="yes" title="Main API">
+        <tab type="usergroup"  title="SIMD Abstractions">
+          <tab type="user" url="@ref simd_types"    title="SIMD Types"/>
+          <tab type="user" url="@ref conditional"   title="Conditional Expressions"/>
+          <tab type="user" url="@ref memory"        title="Memory Management"/>
+          <tab type="user" url="@ref simd_concepts" title="Concepts"/>
+        </tab>
+        <tab type="usergroup" visible="yes" title="Core Functions">
+          <tab type="user" url="@ref core_arithmetic"     title="Arithmetic Operations"/>
+          <tab type="user" url="@ref core_fma_family"     title="FMA-like Operations"/>
+          <tab type="user" url="@ref core_bitops"         title="Bitwise Functions"/>
+          <tab type="user" url="@ref core_logical"        title="Logical Operations"/>
+          <tab type="user" url="@ref core_predicates"     title="Predicates"/>
+          <tab type="user" url="@ref core_conversions"    title="Conversions"/>
+          <tab type="user" url="@ref core_internal"       title="IEEE-754 Operations"/>
+          <tab type="user" url="@ref core_accuracy"       title="Accuracy Helpers"/>
+          <tab type="user" url="@ref core_decorators"     title="Options"/>
+        </tab>
+        <tab type="usergroup" visible="yes" title="Constants">
+          <tab type="user" url="@ref core_constants"      title="Generic Constants"/>
+          <tab type="user" url="@ref math_constants"      title="Math Constants"/>
+        </tab>
+        <tab type="usergroup" visible="yes" title="Common Math Functions">
+          <tab type="user" url="@ref math_log"      title="Logarithm"/>
+          <tab type="user" url="@ref math_exp"      title="Exponential"/>
+          <tab type="user" url="@ref math_trig"     title="Trigonometric"/>
+          <tab type="user" url="@ref math_invtrig"  title="Inverse Trigonometric"/>
+          <tab type="user" url="@ref math_hyper"    title="Hyperbolic"/>
+          <tab type="user" url="@ref math_invhyper" title="Inverse Hyperbolic"/>
+        </tab>
+        <tab type="usergroup" visible="yes" title="Advanced Math Functions">
+          <tab type="user" url="@ref bessel"        title="Bessel functions"/>
+          <tab type="user" url="@ref combinatorial" title="Combinatorial functions"/>
+          <tab type="user" url="@ref elliptic"      title="Elliptic functions"/>
+          <tab type="user" url="@ref polynomial"    title="Polynomial functions"/>
+          <tab type="user" url="@ref special"       title="Special functions"/>
+        </tab>
+        <tab type="usergroup" visible="yes" title="SIMD Specifics">
+          <tab type="user" url="@ref core_compress"       title="Compress functions"/>
+          <tab type="user" url="@ref core_simd"           title="SWAR Operations"/>
+          <tab type="user" url="@ref core_named_shuffles" title="Named Shuffles"/>
+          <tab type="user" url="@ref core_reduction"      title="Reductions"/>
+        </tab>
+        <tab type="usergroup" visible="yes" title="Algorithms &amp; Views">
+          <tab type="user" url="@ref algos"         title="Algorithms"/>
+          <tab type="user" url="@ref views"         title="Views"/>
+          <tab type="user" url="@ref algo_traits"   title="Options"/>
+          <tab type="user" url="@ref algo_concepts" title="Concepts"/>
+        </tab>
+      </tab>
+      <tab type="usergroup" visible="yes" title="Developer API">
+        <tab type="user" url="@ref traits"      title="Type Traits"/>
+        <tab type="user" url="@ref arch"        title="Architecture Helpers"/>
+        <tab type="user" url="@ref extensions"  title="Functions and Callables"/>
+        <tab type="user" url="@ref struct"      title="User-Defined Types Supports"/>
+      </tab>
+      <tab type="concepts" visible="yes"      title="Concepts List"/>
     </tab>
-    <tab type="files" visible="yes" title="">
-      <tab type="filelist" visible="yes" title="" intro=""/>
-      <tab type="globals" visible="yes" title="" intro=""/>
+    <tab type="usergroup" visible="yes" title="About The Library">
+      <tab type="user" url="@ref glossary_semantic" title="Glossary"/>
+      <tab type="user" url="@ref changelog" title="Changelog"/>
+      <tab type="usergroup" visible="yes" title="EVE Development">
+        <tab type="user" url="@ref dev_environment" title="Environment"/>
+        <tab type="user" url="@ref dev_cmake" title="CMake Usage"/>
+      </tab>
+      <tab type="usergroup" visible="yes" title="Rationale">
+        <tab type="user" url="@ref design_rationale" title="Design Decisions"/>
+        <tab type="user" url="@ref algo_rationale" title="SIMD Algorithms"/>
+      </tab>
+      <tab type="user" url="@ref licence" title="Licence"/>
     </tab>
-    <tab type="examples" visible="yes" title="" intro=""/>
+
   </navindex>
 
   <!-- Layout definition for a class page -->

diff --git a/doc/page10_licence.md → doc/licence.md b/doc/page10_licence.md → doc/licence.md
diff --git a/doc/page02_tutorial.md b/doc/page02_tutorial.md
diff --git a/doc/page09_internals.md b/doc/page09_internals.md
diff --git a/doc/page01_info.md → doc/setup.md b/doc/page01_info.md → doc/setup.md
@@ -1,4 +1,4 @@
-Installation & Quick Start {#install}
+Installation & Quick Start {#setup}
 ==========================
 
 # Pre-requisites
@@ -10,32 +10,28 @@ Installation & Quick Start {#install}
 | g++            | 11  or above   |
 | clang++        | 13  or above   |
 
-<br/>
-
-In term of SIMD extension sets, we actively supports (ie code is optimized and regularly tested) the following:
+In term of SIMD extension sets, the supports status are as follows:
 
-- **Intel**
-  - SSE2, SSSE3, SSE3, SSE4.1, SSE4.2
-  - AVX, AVX2, FMA3
-  - AVX512 in SKylake-AVX512 mode (F, CD, VL, DQ, BW)
-- **ARM**
-  - NEON A32 (64 & 128 bits)
-  - NEON A64 (64 & 128 bits)
-  - ASIMD
-  - SVE with fixed sizes of 128, 256 and 512 bits registers.
+- Active Support  (ie code is optimized and regularly tested)
 
-Partial/In-progress support with minimal checks:
- - **PowerPC**
-   - VMX
-   - VSX
+  - **Intel**
+    - SSE2, SSSE3, SSE3, SSE4.1, SSE4.2
+    - AVX, AVX2, FMA3
+    - AVX512 in SKylake-AVX512 mode (F, CD, VL, DQ, BW)
+  - **ARM**
+    - NEON A32 (64 & 128 bits)
+    - NEON A64 (64 & 128 bits)
+    - ASIMD
+    - SVE with fixed sizes of 128, 256 and 512 bits registers.
 
- - We **do not support** ARM SVE with dynamic size.
- - We **do not support** GPGPU, this is the job for another tool.
-The following instructions are tentatively supported (ie code is incomplete and not tested in depth):
+- Partial/In-progress support with minimal checks:
+  - **PowerPC**
+    - Altivec for Power7 to 9
+    - VSX for Power9
 
-- **PowerPC**
-  - Altivec for Power7 to 9
-  - VSX for Power9
+- No Support
+  - We **do not support** ARM SVE with dynamic size.
+  - We **do not support** GPGPU, this is the job for another tool.
 
 # Retrieving the source
 
@@ -90,34 +86,9 @@ Once installed, you can use **EVE** headers directly from your
 yay -S eve-git
 ```
 
-## Conan
-
-[**Conan Center**](https://conan.io/center/) hosts **EVE** as the
-[`jfalcou-eve` package](https://conan.io/center/jfalcou-eve).
-
-To use **EVE**, just add `jfalcou-eve/v2021.10.0` in the `[requires]` section of
-your `conanfile.txt`
-
-```cmake
-[requires]
-jfalcou-eve/v2021.10.0
-
-[generators]
-cmake
-```
-
-## VCPKG
-
-**EVE** can be fetched from [VCPKG](https://vcpkgx.com/details.html?package=eve). Note that, as of
-now, we still don't support MSVC.
-
-```bash
-vcpkg install eve
-```
-
 # Installation from Source
 
-If you didn't fetched **EVE** from a package manager, you'll need to install it via our CMake
+If you didn't fetched **EVE** from a package manager, you'll need to install it via your CMake
 system.
 
 ## Setting up the Library
@@ -153,26 +124,13 @@ using the `doxygen` target:
 cmake --build build --target doxygen
 @endcode
 
-The resulting HTML files will be available in the `docs` folder.
-
-You can also build **EVE** documentation in your build folder by using the  `doxygen-local` target:
-<br/>
-
-@code
-cmake --build build --target doxygen-local
-@endcode
-
 The resulting HTML files will be available in the `docs` folder inside your build folder.
 
 # Using the library
 
 ## Compilation
 
-Once installed, you can compile the following code to check if everything is alright.
-
-@godbolt{examples/quick-start/sanity-check.cpp}
-
-To do so, use your C++20 aware favorite compiler, for example g++.
+To compiel code using **EVE**, use your C++20 aware favorite compiler, for example g++.
 
 @verbatim
 $ g++ test.cpp -std=c++20  -march=native -O3 -DNDEBUG -I/path/to/install/include/eve-<version> -o output
@@ -194,21 +152,17 @@ You can also select a specific instructions set by using the proper option(s) fr
 $ g++ test.cpp -std=c++20  -msse4.1 -O3 -DNDEBUG -I/path/to/install/include/eve-<version> -o output
 @endverbatim
 
+
 ## Execution
 
 Once done, execute the binary. If you compiled for SSE4.1 for example, you'll end up with the
 following results:
 
-@verbatim
-$ ./output
- x     = (1, 2, 3, 4)
- 2*x   = (2, 4, 6, 8)
- x^0.5 = (1, 1.41421, 1.73205, 2)
-@endverbatim
+@godbolt{examples/quick-start/sanity-check.cpp}
 
 That's it, **EVE** is properly installed and ready to use.
 
-## Use in CMake
+## Use with CMake
 
 Once installed, **EVE** may be consumed through its config-file **CMake** package. Simply find and
 link against **EVE's** **CMake** target, as you would any other **CMake** library, and then
@@ -220,30 +174,31 @@ find_package(eve CONFIG REQUIRED)
 target_link_libraries(use-eve PRIVATE eve::eve)
 ```
 
-> If a custom installation prefix was used, ensure your **EVE** installation is within **CMake's**
-  search path with the use of the **CMake** variables **eve_ROOT**, **eve_DIR**, or
-  **CMAKE_PREFIX_PATH**.
+If a custom installation prefix was used, ensure your **EVE** installation is within **CMake's**
+search path with the use of the **CMake** variables **eve_ROOT**, **eve_DIR**, or
+**CMAKE_PREFIX_PATH**.
 
 # Advanced options
 
 If you want to dig a bit further, you can pass additional options to `cmake` to
 activate additional features.
 
-|Option                   |Effect                                                   |Target        |
-|-------------------------|:--------------------------------------------------------|:-------------|
-| `EVE_BUILD_TEST`        |Enable unit tests for **EVE** (`ON` by default).         | `unit`       |
-| `EVE_BUILD_BENCHMARKS`  |Enable benchmark tests for **EVE** (`OFF` by default).   | `benchmarks` |
-| `EVE_BUILD_RANDOM`      |Enable random tests for **EVE** (`OFF` by default).      | `random`     |
-| `EVE_BUILD_INTEGRATION` |Enable integration tests for **EVE** (`OFF` by default). | `integration`|
+|Option                     |Effect                                                       |Target        |
+|---------------------------|:------------------------------------------------------------|:-------------|
+| `EVE_BUILD_TEST`          |Enable unit tests for **EVE** (`ON` by default).             | `unit`       |
+| `EVE_BUILD_BENCHMARKS`    |Enable benchmark tests for **EVE** (`OFF` by default).       | `benchmarks` |
+| `EVE_BUILD_RANDOM`        |Enable random tests for **EVE** (`OFF` by default).          | `random`     |
+| `EVE_BUILD_DOCUMENTATION` |Enable the generation of the documentation (`ON` by default).| `doxygen`|
 
 There is currently over 2000 tests, so compiling all unit tests may require a large machine or some
 time. We recommend compiling in parallel using `-j`.
+
 All available **CMake** targets may be listed via `cmake --build build --target help`, each of which
 may be built individually.
 
 Some options are also available to control some other aspects
 
-| Option | Effect       | Comments               |
-|--------|:-------------|:---------------------|
-| `EVE_USE_BMI_ON_AVX2` | Enables using bmi instructions on avx2                 | on Intel, it's beneficial, on AMD it's a disaster |
-| `EVE_USE_PCH`         | Enable using precompiled headers for **EVE** tests.    | This is `ON` by default  |
+| Option                | Effect                                              | Comments                               |
+|-----------------------|:----------------------------------------------------|:---------------------------------------|
+| `EVE_USE_BMI_ON_AVX2` | Enables using bmi instructions on AVX2              | Beneficial on Intel, disastrous on AMD |
+| `EVE_USE_PCH`         | Enable using precompiled headers for **EVE** tests. | This is `ON` by default                |