DOC: RST Titles Underline reordering (#21677)

* ~ not ^

* = skipped for -

* swap - and = underline in files they are swapped

* * to = in header underline

* - to = and * to - for consitency

* A few more change * -> ~

* use ~ instead of +

* DOC: Fixup `c-api/array.rst` with further ^ with ~ replacement

There is still a fourth level here, which remains using "

Co-authored-by: Sebastian Berg <sebastian@sipsolutions.net>

11 files changed, 45 insertions, 45 deletions

diff --git a/doc/source/reference/random/bit_generators/index.rst b/doc/source/reference/random/bit_generators/index.rst
index 211f0d60e..d93f38d0b 100644
--- a/doc/source/reference/random/bit_generators/index.rst
+++ b/doc/source/reference/random/bit_generators/index.rst
@@ -1,7 +1,7 @@
 .. currentmodule:: numpy.random
 
 Bit Generators
---------------
+==============
 
 The random values produced by :class:`~Generator`
 originate in a BitGenerator.  The BitGenerators do not directly provide
@@ -11,7 +11,7 @@ low-level wrappers for consumption by code that can efficiently
 access the functions provided, e.g., `numba <https://numba.pydata.org>`_.
 
 Supported BitGenerators
-=======================
+-----------------------
 
 The included BitGenerators are:
 
@@ -51,7 +51,7 @@ The included BitGenerators are:
     SFC64 <sfc64>
 
 Seeding and Entropy
--------------------
+===================
 
 A BitGenerator provides a stream of random values. In order to generate
 reproducible streams, BitGenerators support setting their initial state via a
diff --git a/doc/source/reference/random/bit_generators/mt19937.rst b/doc/source/reference/random/bit_generators/mt19937.rst
index d05ea7c6f..e85234d10 100644
--- a/doc/source/reference/random/bit_generators/mt19937.rst
+++ b/doc/source/reference/random/bit_generators/mt19937.rst
@@ -1,5 +1,5 @@
 Mersenne Twister (MT19937)
---------------------------
+==========================
 
 .. currentmodule:: numpy.random
 
@@ -8,7 +8,7 @@ Mersenne Twister (MT19937)
     :exclude-members: __init__
 
 State
-=====
+-----
 
 .. autosummary::
    :toctree: generated/
@@ -16,14 +16,14 @@ State
    ~MT19937.state
 
 Parallel generation
-===================
+-------------------
 .. autosummary::
    :toctree: generated/
 
    ~MT19937.jumped
 
 Extending
-=========
+---------
 .. autosummary::
    :toctree: generated/
 
diff --git a/doc/source/reference/random/bit_generators/pcg64.rst b/doc/source/reference/random/bit_generators/pcg64.rst
index 889965f77..6ebd34f4a 100644
--- a/doc/source/reference/random/bit_generators/pcg64.rst
+++ b/doc/source/reference/random/bit_generators/pcg64.rst
@@ -1,5 +1,5 @@
 Permuted Congruential Generator (64-bit, PCG64)
------------------------------------------------
+===============================================
 
 .. currentmodule:: numpy.random
 
@@ -8,7 +8,7 @@ Permuted Congruential Generator (64-bit, PCG64)
     :exclude-members: __init__
 
 State
-=====
+-----
 
 .. autosummary::
    :toctree: generated/
@@ -16,7 +16,7 @@ State
    ~PCG64.state
 
 Parallel generation
-===================
+-------------------
 .. autosummary::
    :toctree: generated/
 
@@ -24,7 +24,7 @@ Parallel generation
    ~PCG64.jumped
 
 Extending
-=========
+---------
 .. autosummary::
    :toctree: generated/
 
diff --git a/doc/source/reference/random/bit_generators/pcg64dxsm.rst b/doc/source/reference/random/bit_generators/pcg64dxsm.rst
index e37efa5d3..99e4d15c9 100644
--- a/doc/source/reference/random/bit_generators/pcg64dxsm.rst
+++ b/doc/source/reference/random/bit_generators/pcg64dxsm.rst
@@ -1,5 +1,5 @@
 Permuted Congruential Generator (64-bit, PCG64 DXSM)
-----------------------------------------------------
+====================================================
 
 .. currentmodule:: numpy.random
 
@@ -8,7 +8,7 @@ Permuted Congruential Generator (64-bit, PCG64 DXSM)
     :exclude-members: __init__
 
 State
-=====
+-----
 
 .. autosummary::
    :toctree: generated/
@@ -16,7 +16,7 @@ State
    ~PCG64DXSM.state
 
 Parallel generation
-===================
+-------------------
 .. autosummary::
    :toctree: generated/
 
@@ -24,7 +24,7 @@ Parallel generation
    ~PCG64DXSM.jumped
 
 Extending
-=========
+---------
 .. autosummary::
    :toctree: generated/
 
diff --git a/doc/source/reference/random/bit_generators/philox.rst b/doc/source/reference/random/bit_generators/philox.rst
index 3c2fa4cc5..4df364653 100644
--- a/doc/source/reference/random/bit_generators/philox.rst
+++ b/doc/source/reference/random/bit_generators/philox.rst
@@ -1,5 +1,5 @@
 Philox Counter-based RNG
-------------------------
+========================
 
 .. currentmodule:: numpy.random
 
@@ -8,7 +8,7 @@ Philox Counter-based RNG
     :exclude-members: __init__
 
 State
-=====
+-----
 
 .. autosummary::
    :toctree: generated/
@@ -16,7 +16,7 @@ State
    ~Philox.state
 
 Parallel generation
-===================
+-------------------
 .. autosummary::
    :toctree: generated/
 
@@ -24,7 +24,7 @@ Parallel generation
    ~Philox.jumped
 
 Extending
-=========
+---------
 .. autosummary::
    :toctree: generated/
 
diff --git a/doc/source/reference/random/bit_generators/sfc64.rst b/doc/source/reference/random/bit_generators/sfc64.rst
index 8cb255bc1..6ea9593c2 100644
--- a/doc/source/reference/random/bit_generators/sfc64.rst
+++ b/doc/source/reference/random/bit_generators/sfc64.rst
@@ -1,5 +1,5 @@
 SFC64 Small Fast Chaotic PRNG
------------------------------
+=============================
 
 .. currentmodule:: numpy.random
 
@@ -8,7 +8,7 @@ SFC64 Small Fast Chaotic PRNG
     :exclude-members: __init__
 
 State
-=====
+-----
 
 .. autosummary::
    :toctree: generated/
@@ -16,7 +16,7 @@ State
    ~SFC64.state
 
 Extending
-=========
+---------
 .. autosummary::
    :toctree: generated/
 
diff --git a/doc/source/reference/random/extending.rst b/doc/source/reference/random/extending.rst
index 2c506e943..6bb941496 100644
--- a/doc/source/reference/random/extending.rst
+++ b/doc/source/reference/random/extending.rst
@@ -3,14 +3,14 @@
 .. _extending:
 
 Extending
----------
+=========
 The BitGenerators have been designed to be extendable using standard tools for
 high-performance Python -- numba and Cython.  The `~Generator` object can also
 be used with user-provided BitGenerators as long as these export a small set of
 required functions.
 
 Numba
-=====
+-----
 Numba can be used with either CTypes or CFFI.  The current iteration of the
 BitGenerators all export a small set of functions through both interfaces.
 
@@ -30,7 +30,7 @@ the `examples` section below.
 .. _random_cython:
 
 Cython
-======
+------
 
 Cython can be used to unpack the ``PyCapsule`` provided by a BitGenerator.
 This example uses `PCG64` and the example from above.  The usual caveats
@@ -61,7 +61,7 @@ See :ref:`extending_cython_example` for the complete listings of these examples
 and a minimal ``setup.py`` to build the c-extension modules.
 
 CFFI
-====
+----
 
 CFFI can be used to directly access the functions in
 ``include/numpy/random/distributions.h``. Some "massaging" of the header
@@ -80,7 +80,7 @@ directly from the ``_generator`` shared object, using the `BitGenerator.cffi` in
 
 
 New Bit Generators
-==================
+------------------
 `~Generator` can be used with user-provided `~BitGenerator`\ s. The simplest
 way to write a new BitGenerator is to examine the pyx file of one of the
 existing BitGenerators. The key structure that must be provided is the
@@ -109,7 +109,7 @@ the next 64-bit unsigned integer function if not needed. Functions inside
   bitgen_state->next_uint64(bitgen_state->state)
 
 Examples
-========
+--------
 
 .. toctree::
     Numba <examples/numba>
diff --git a/doc/source/reference/random/generator.rst b/doc/source/reference/random/generator.rst
index 9bee4d756..dc71cb1f9 100644
--- a/doc/source/reference/random/generator.rst
+++ b/doc/source/reference/random/generator.rst
@@ -1,7 +1,7 @@
 .. currentmodule:: numpy.random
 
 Random Generator
-----------------
+================
 The `~Generator` provides access to
 a wide range of distributions, and served as a replacement for
 :class:`~numpy.random.RandomState`.  The main difference between
@@ -19,14 +19,14 @@ can be changed by passing an instantized BitGenerator to ``Generator``.
     :exclude-members: __init__
 
 Accessing the BitGenerator
-==========================
+--------------------------
 .. autosummary::
    :toctree: generated/
 
    ~numpy.random.Generator.bit_generator
 
 Simple random data
-==================
+------------------
 .. autosummary::
    :toctree: generated/
 
@@ -36,7 +36,7 @@ Simple random data
    ~numpy.random.Generator.bytes
 
 Permutations
-============
+------------
 The methods for randomly permuting a sequence are
 
 .. autosummary::
@@ -140,7 +140,7 @@ For example,
     ['B', 'D', 'A', 'E', 'C']  # random
 
 Distributions
-=============
+-------------
 .. autosummary::
    :toctree: generated/
 
diff --git a/doc/source/reference/random/legacy.rst b/doc/source/reference/random/legacy.rst
index 42437dbb6..b1fce49a1 100644
--- a/doc/source/reference/random/legacy.rst
+++ b/doc/source/reference/random/legacy.rst
@@ -52,7 +52,7 @@ using the state of the `RandomState`:
     :exclude-members: __init__
 
 Seeding and State
-=================
+-----------------
 
 .. autosummary::
    :toctree: generated/
@@ -62,7 +62,7 @@ Seeding and State
    ~RandomState.seed
 
 Simple random data
-==================
+------------------
 .. autosummary::
    :toctree: generated/
 
@@ -75,7 +75,7 @@ Simple random data
    ~RandomState.bytes
 
 Permutations
-============
+------------
 .. autosummary::
    :toctree: generated/
 
@@ -83,7 +83,7 @@ Permutations
    ~RandomState.permutation
 
 Distributions
-=============
+-------------
 .. autosummary::
    :toctree: generated/
 
@@ -124,7 +124,7 @@ Distributions
    ~RandomState.zipf
 
 Functions in `numpy.random`
-===========================
+---------------------------
 Many of the RandomState methods above are exported as functions in
 `numpy.random` This usage is discouraged, as it is implemented via a global
 `RandomState` instance which is not advised on two counts:
diff --git a/doc/source/reference/random/performance.rst b/doc/source/reference/random/performance.rst
index cb9b94113..3a7cb027e 100644
--- a/doc/source/reference/random/performance.rst
+++ b/doc/source/reference/random/performance.rst
@@ -1,10 +1,10 @@
 Performance
------------
+===========
 
 .. currentmodule:: numpy.random
 
 Recommendation
-**************
+--------------
 
 The recommended generator for general use is `PCG64` or its upgraded variant
 `PCG64DXSM` for heavily-parallel use cases. They are statistically high quality,
@@ -31,7 +31,7 @@ many systems.
 .. _`fails some statistical tests`: https://www.iro.umontreal.ca/~lecuyer/myftp/papers/testu01.pdf
 
 Timings
-*******
+-------
 
 The timings below are the time in ns to produce 1 random value from a
 specific distribution.  The original `MT19937` generator is
@@ -86,7 +86,7 @@ performance was computed using a geometric mean.
    All timings were taken using Linux on an AMD Ryzen 9 3900X processor.
 
 Performance on different Operating Systems
-******************************************
+------------------------------------------
 Performance differs across platforms due to compiler and hardware availability
 (e.g., register width) differences. The default bit generator has been chosen
 to perform well on 64-bit platforms.  Performance on 32-bit operating systems
diff --git a/doc/source/reference/random/upgrading-pcg64.rst b/doc/source/reference/random/upgrading-pcg64.rst
index 9e540ace9..b36bdf4c8 100644
--- a/doc/source/reference/random/upgrading-pcg64.rst
+++ b/doc/source/reference/random/upgrading-pcg64.rst
@@ -3,7 +3,7 @@
 .. currentmodule:: numpy.random
 
 Upgrading ``PCG64`` with ``PCG64DXSM``
---------------------------------------
+======================================
 
 Uses of the `PCG64` `BitGenerator` in a massively-parallel context have been
 shown to have statistical weaknesses that were not apparent at the first
@@ -15,7 +15,7 @@ the statistical weakness while preserving the performance and the features of
 `PCG64`.
 
 Does this affect me?
-====================
+--------------------
 
 If you
 
@@ -48,7 +48,7 @@ swamped by the remaining streams in most applications.
 .. _upgrading-pcg64-details:
 
 Technical Details
-=================
+-----------------
 
 Like many PRNG algorithms, `PCG64` is constructed from a transition function,
 which advances a 128-bit state, and an output function, that mixes the 128-bit