Improve documentation

serge-sans-paille · serge-sans-paille · commit 801de0a57897 · 2025-12-01T06:21:52.000Z
- Add some note on integration, as a followup to #1207 - Harmonize capitalization of titles And generic documentation improvements to make things, hopefully, easier to understand.
diff --git a/docs/Doxyfile b/docs/Doxyfile
@@ -45,4 +45,6 @@ WARN_AS_ERROR = NO
 ENABLE_PREPROCESSING = YES
 MACRO_EXPANSION      = YES
 EXPAND_ONLY_PREDEF   = YES
-PREDEFINED           = XSIMD_NO_DISCARD= XSIMD_INLINE=inline DOXYGEN_SHOULD_SKIP_THIS=
+PREDEFINED           = XSIMD_NO_DISCARD= \
+                       XSIMD_INLINE=inline \
+                       DOXYGEN_SHOULD_SKIP_THIS=
diff --git a/docs/source/api/aligned_allocator.rst b/docs/source/api/aligned_allocator.rst
@@ -4,17 +4,17 @@
 
    The full license is in the file LICENSE, distributed with this software.
 
-Alignment manipulation
+Alignment Manipulation
 ======================
 
-Aligned memory allocator
+Aligned Memory Allocator
 ------------------------
 
 .. doxygenclass:: xsimd::aligned_allocator
    :project: xsimd
    :members:
 
-Alignement checker
+Alignement Checker
 ------------------
 
 .. doxygenfunction:: xsimd::is_aligned
diff --git a/docs/source/api/arch.rst b/docs/source/api/arch.rst
@@ -4,7 +4,7 @@
 
    The full license is in the file LICENSE, distributed with this software.
 
-Architecture manipulation
+Architecture Manipulation
 =========================
 
 xsimd provides an high level description of the instruction sets it manipulates.
@@ -19,7 +19,7 @@ The best available architecture is available at compile time through
    :members:
 
 
-Emulated mode
+Emulated Mode
 -------------
 
 When compiled with the macro ``XSIMD_WITH_EMULATED`` set to ``1``, xsimd also
diff --git a/docs/source/api/arithmetic_index.rst b/docs/source/api/arithmetic_index.rst
@@ -26,8 +26,10 @@
    }
    </style>
 
-Arithmetic operators
-====================
+.. _Arithmetic Operations:
+
+Arithmetic Operations
+=====================
 
 Binary operations:
 
diff --git a/docs/source/api/batch_index.rst b/docs/source/api/batch_index.rst
@@ -4,7 +4,9 @@
 
    The full license is in the file LICENSE, distributed with this software.
 
-Batch types
+.. _Batch Types:
+
+Batch Types
 ===========
 
 .. toctree::
diff --git a/docs/source/api/batch_manip.rst b/docs/source/api/batch_manip.rst
@@ -4,7 +4,7 @@
 
    The full license is in the file LICENSE, distributed with this software.
 
-Conditional expression
+Conditional Expression
 ======================
 
 +------------------------------+-------------------------------------------+
diff --git a/docs/source/api/bitwise_operators_index.rst b/docs/source/api/bitwise_operators_index.rst
@@ -26,7 +26,7 @@
    }
    </style>
 
-Bitwise operators
+Bitwise Operators
 =================
 
 +---------------------------------------+----------------------------------------------------+
diff --git a/docs/source/api/cast_index.rst b/docs/source/api/cast_index.rst
@@ -27,7 +27,7 @@
    </style>
 
 
-Type conversion
+Type Conversion
 ===============
 
 Cast:
diff --git a/docs/source/api/comparison_index.rst b/docs/source/api/comparison_index.rst
@@ -26,7 +26,7 @@
    }
    </style>
 
-Comparison operators
+Comparison Operators
 ====================
 
 Ordering:
diff --git a/docs/source/api/data_transfer.rst b/docs/source/api/data_transfer.rst
@@ -4,8 +4,10 @@
 
    The full license is in the file LICENSE, distributed with this software.
 
-Data transfer
-=============
+.. _Data Transfer:
+
+Data Transfers
+==============
 
 From memory:
 
diff --git a/docs/source/api/instr_macros.rst b/docs/source/api/instr_macros.rst
@@ -26,7 +26,7 @@
    }
    </style>
 
-Instruction set macros
+Instruction Set Macros
 ======================
 
 Each of these macros corresponds to an instruction set supported by XSIMD. They
@@ -36,7 +36,7 @@ can be used to filter arch-specific code.
    :project: xsimd
    :content-only:
 
-Changing Default architecture
+Changing Default Architecture
 *****************************
 
 You can change the default instruction set used by xsimd (when none is provided
diff --git a/docs/source/api/math_index.rst b/docs/source/api/math_index.rst
@@ -27,7 +27,7 @@
    </style>
 
 
-Mathematical functions
+Mathematical Functions
 ======================
 
 Basic functions:
diff --git a/docs/source/api/reducer_index.rst b/docs/source/api/reducer_index.rst
@@ -26,7 +26,7 @@
    }
    </style>
 
-Reduction operators
+Reduction Operators
 ===================
 
 +---------------------------------------+----------------------------------------------------+
diff --git a/docs/source/api/xsimd_batch.rst b/docs/source/api/xsimd_batch.rst
@@ -4,7 +4,7 @@
 
    The full license is in the file LICENSE, distributed with this software.
 
-Batch of scalars
+Batch of Scalars
 ================
 
 .. _xsimd-batch-ref:
diff --git a/docs/source/api/xsimd_batch_bool.rst b/docs/source/api/xsimd_batch_bool.rst
@@ -4,7 +4,7 @@
 
    The full license is in the file LICENSE, distributed with this software.
 
-Batch of conditions
+Batch of Conditions
 ===================
 
 .. _xsimd-batch-bool-ref:
@@ -13,7 +13,7 @@ Batch of conditions
    :project: xsimd
    :members:
 
-Logical operators
+Logical Operators
 -----------------
 
 .. doxygengroup:: batch_bool_logical
diff --git a/docs/source/api/xsimd_batch_complex.rst b/docs/source/api/xsimd_batch_complex.rst
@@ -4,24 +4,26 @@
 
    The full license is in the file LICENSE, distributed with this software.
 
-Batch of complex numbers
+Batch of Complex Numbers
 ========================
 
 .. doxygenclass:: xsimd::batch< std::complex< T >, A >
    :project: xsimd
    :members:
 
-Operations specific to batches of complex numbers
+Operations Specific to Batches of Complex Numbers
 -------------------------------------------------
 
 .. doxygengroup:: batch_complex
    :project: xsimd
    :content-only:
 
-XTL complex support
+XTL Complex Support
 -------------------
 
 If the preprocessor token ``XSIMD_ENABLE_XTL_COMPLEX`` is defined, ``xsimd``
 provides constructors of ``xsimd::batch< std::complex< T >, A >`` from
-``xtl::xcomplex``, similar to those for ``std::complex``.  This requires ``xtl``
+``xtl::xcomplex``, similar to those for ``std::complex``.  This requires `XTL`_
 to be installed.
+
+.. _XTL: https://github.com/xtensor-stack/xtl
diff --git a/docs/source/api/xsimd_batch_constant.rst b/docs/source/api/xsimd_batch_constant.rst
@@ -4,7 +4,7 @@
 
    The full license is in the file LICENSE, distributed with this software.
 
-Batch of constants
+Batch of Constants
 ==================
 
 .. _xsimd-batch-constant-ref:
diff --git a/docs/source/basic_usage.rst b/docs/source/basic_usage.rst
@@ -4,41 +4,50 @@
 
    The full license is in the file LICENSE, distributed with this software.
 
-Basic usage
+Basic Usage
 ===========
 
-Manipulating abstract batches
+Manipulating Abstract Batches
 -----------------------------
 
 Here is an example that computes the mean of two batches, using the best
 architecture available, based on compile time informations:
 
 .. literalinclude:: ../../test/doc/manipulating_abstract_batches.cpp
 
-The batch can be a batch of 4 single precision floating point numbers (e.g. on
-Neon) or a batch of 8 (e.g. on AVX2).
+There is no explicit architectural information available in the code, those are
+deduced from the compiler target and its vector instruction support. If several
+vector instructions sets are supported, the one with widest register width and
+most operations is picked (e.g. AVX2 over AVX over SSE4.1).
 
-Manipulating parametric batches
+There is no explicit register size information available in the code, those
+solely depend on the architecture picked, as stated above. The batch can be a
+batch of 4 single precision floating point numbers (e.g. on Neon) or a batch of
+8 (e.g. on AVX2).
+
+Manipulating Parametric Batches
 -------------------------------
 
-The previous example can be made fully parametric, both in the batch type and
-the underlying architecture. This is achieved as described in the following
-example:
+The implicit architectural information from previous example can be made
+explicit, and the type used can be parametric. This is achieved as described in
+the following example:
 
 .. literalinclude:: ../../test/doc/manipulating_parametric_batches.cpp
 
 At its core, a :cpp:class:`xsimd::batch` is bound to the scalar type it contains, and to the
 instruction set it can use to operate on its values.
 
-Explicit use of an instruction set extension
+Explicit Use of an Instruction Set Extension
 --------------------------------------------
 
 Here is an example that loads two batches of 4 double floating point values, and
 computes their mean, explicitly using the AVX extension:
 
 .. literalinclude:: ../../test/doc/explicit_use_of_an_instruction_set.cpp
 
-Note that in that case, the instruction set is explicilty specified in the batch type.
+Note that in that case, the instruction set is explicilty specified in the batch
+type. The flag passed down to the compiler need to make it possible for this
+architecture to be used.
 
 This example outputs:
 
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -16,10 +16,16 @@ Introduction
 on a batch of values at once, and thus provide a way to significantly accelerate code execution. However, these instructions differ between microprocessor
 vendors and compilers.
 
-`xsimd` provides a unified means for using these features for library authors. Namely, it enables manipulation of batches of scalar and complex numbers with the same arithmetic
-operators and common mathematical functions as for single values.
+`xsimd` provides a unified means for using these features for library authors.
 
-There are several ways to use `xsimd`:
+The core of the library consist in a parametrized vector type, :ref:`Batch Types`,
+and a set of operations to perform :ref:`Arithmetic Operations`,
+:ref:`Data Transfer`, and many common mathemtical functions, as for single
+values.
+
+
+There are several ways to use `xsimd` using those :ref:`Batch Types` and
+operations:
 
 - one can write a generic, vectorized, algorithm and compile it as part of their
   application build, with the right architecture flag;
@@ -34,20 +40,13 @@ There are several ways to use `xsimd`:
 Of course, nothing prevents the combination of several of those approach, but
 more about this in section :ref:`Writing vectorized code`.
 
-You can find out more about this implementation of C++ wrappers for SIMD intrinsics at the `The C++ Scientist`_. The mathematical functions are a
+You can find out more about this implementation of C++ wrappers for SIMD
+intrinsics at the `The C++ Scientist`_. The mathematical functions are a
 lightweight implementation of the algorithms also used in `boost.SIMD`_.
 
-`xsimd` requires a C++11 compliant compiler. The following C++ compilers are supported:
 
-+-------------------------+-------------------------------+
-| Compiler                | Version                       |
-+=========================+===============================+
-| Microsoft Visual Studio | MSVC 2015 update 2 and above  |
-+-------------------------+-------------------------------+
-| g++                     | 4.9 and above                 |
-+-------------------------+-------------------------------+
-| clang                   | 3.7 and above                 |
-+-------------------------+-------------------------------+
+Compiler and Architecture Support
+---------------------------------
 
 The following SIMD instruction set extensions are supported:
 
@@ -69,6 +68,19 @@ The following SIMD instruction set extensions are supported:
 | PowerPC      | VSX                                                     |
 +--------------+---------------------------------------------------------+
 
+
+`xsimd` requires a C++11 compliant compiler. The following C++ compilers are supported:
+
++-------------------------+-------------------------------+
+| Compiler                | Version                       |
++=========================+===============================+
+| Microsoft Visual Studio | MSVC 2015 update 2 and above  |
++-------------------------+-------------------------------+
+| g++                     | 4.9 and above                 |
++-------------------------+-------------------------------+
+| clang                   | 3.7 and above                 |
++-------------------------+-------------------------------+
+
 Licensing
 ---------
 
@@ -90,6 +102,7 @@ This software is licensed under the BSD-3-Clause license. See the LICENSE file f
 
    basic_usage
    vectorized_code
+   integration
 
 .. toctree::
    :caption: API REFERENCE
diff --git a/docs/source/installation.rst b/docs/source/installation.rst
@@ -28,7 +28,7 @@ Besides the `xsimd` headers, all these methods place the ``cmake`` project confi
 
 .. image:: conda.svg
 
-Using the conda-forge package
+Using the conda-forge Package
 -----------------------------
 
 A package for `xsimd` is available for the `mamba <https://mamba.readthedocs.io>`_ (or `conda <https://conda.io>`_) package manager.
@@ -39,7 +39,7 @@ A package for `xsimd` is available for the `mamba <https://mamba.readthedocs.io>
 
 .. image:: spack.svg
 
-Using the Spack package
+Using the Spack Package
 -----------------------
 
 A package for `xsimd` is available on the `Spack <https://spack.io>`_ package manager.
@@ -51,7 +51,7 @@ A package for `xsimd` is available on the `Spack <https://spack.io>`_ package ma
 
 .. image:: cmake.svg
 
-From source with cmake
+From Source with cmake
 ----------------------
 
 You can install `xsimd` from source with `cmake <https://cmake.org/>`_. On Unix platforms, from the source directory:
diff --git a/docs/source/integration.rst b/docs/source/integration.rst
diff --git a/docs/source/vectorized_code.rst b/docs/source/vectorized_code.rst

Original file line number	Diff line number	Diff line change
`@@ -26,7 +26,7 @@`
`26`	`26`	`}`
`27`	`27`	`</style>`
`28`	`28`
`29`		`-Bitwise operators`
	`29`	`+Bitwise Operators`
`30`	`30`	`=================`
`31`	`31`
`32`	`32`	`+---------------------------------------+----------------------------------------------------+`