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>

34 files changed, 165 insertions, 165 deletions

diff --git a/doc/source/dev/development_gitpod.rst b/doc/source/dev/development_gitpod.rst
index 92cca81fc..4e386867d 100644
--- a/doc/source/dev/development_gitpod.rst
+++ b/doc/source/dev/development_gitpod.rst
@@ -2,7 +2,7 @@
 
 
 Using Gitpod for NumPy development
-=======================================================
+==================================
 
 This section of the documentation will guide you through:
 
@@ -12,7 +12,7 @@ This section of the documentation will guide you through:
 *  working on the NumPy documentation in Gitpod
 
 Gitpod
--------
+------
 
 `Gitpod`_  is an open-source platform for automated and ready-to-code 
 development environments. It enables developers to describe their dev 
@@ -21,7 +21,7 @@ each new task directly from your browser. This reduces the need to install local
 development environments and deal with incompatible dependencies.
 
 Gitpod GitHub integration
---------------------------
+-------------------------
 
 To be able to use Gitpod, you will need to have the Gitpod app installed on your 
 GitHub account, so if
@@ -40,7 +40,7 @@ permissions later on. Click on the green **Install** button
 This will install the necessary hooks for the integration.
 
 Forking the NumPy repository
------------------------------
+----------------------------
 
 The best way to work on NumPy as a contributor is by making a fork of the 
 repository first.
@@ -50,7 +50,7 @@ repository first.
    https://github.com/melissawm/NumPy, except with your GitHub username in place of ``melissawm``.
 
 Starting Gitpod
-----------------
+---------------
 Once you have authenticated to Gitpod through GitHub, you can install the 
 `Gitpod browser extension <https://www.gitpod.io/docs/browser-extension>`_  
 which will add a **Gitpod** button next to the **Code** button in the 
@@ -86,7 +86,7 @@ of tests that make sure NumPy is working as it should, and ``-v`` activates the
 ``--verbose`` option to show all the test output.
 
 Quick workspace tour
----------------------
+--------------------
 Gitpod uses VSCode as the editor. If you have not used this editor before, you 
 can check the Getting started `VSCode docs`_ to familiarize yourself with it.
 
@@ -125,7 +125,7 @@ development experience:
 *  `VSCode Git Graph extension <https://marketplace.visualstudio.com/items?itemName=mhutchie.git-graph>`_
 
 Development workflow with Gitpod
----------------------------------
+--------------------------------
 The  :ref:`development-workflow` section of this documentation contains 
 information regarding the NumPy development workflow. Make sure to check this 
 before working on your contributions.
@@ -144,7 +144,7 @@ When using Gitpod, git is pre configured for you:
       :alt: Gitpod workspace branches plugin screenshot
 
 Rendering the NumPy documentation
-----------------------------------
+---------------------------------
 You can find the detailed documentation on how rendering the documentation with 
 Sphinx works in the :ref:`howto-build-docs` section.
 
@@ -153,7 +153,7 @@ this task is completed, you have two main options to render the documentation
 in Gitpod.
 
 Option 1: Using Liveserve
-***************************
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
 #. View the documentation in ``NumPy/doc/build/html``. You can start with 
    ``index.html`` and browse, or you can jump straight to the file you're 
@@ -170,7 +170,7 @@ Option 1: Using Liveserve
 #. To stop the server click on the **Port: 5500** button on the status bar.
 
 Option 2: Using the rst extension
-***********************************
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 A quick and easy way to see live changes in a ``.rst`` file as you work on it 
 uses the rst extension with docutils.
@@ -200,13 +200,13 @@ FAQ's and troubleshooting
 -------------------------
 
 How long is my Gitpod workspace kept for?
-*****************************************
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Your stopped workspace will be kept for 14 days and deleted afterwards if you do 
 not use them.
 
 Can I come back to a previous workspace?
-*****************************************
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Yes, let's say you stepped away for a while and you want to carry on working on 
 your NumPy contributions. You need to visit https://gitpod.io/workspaces and 
@@ -214,13 +214,13 @@ click on the workspace you want to spin up again. All your changes will be there
 as you last left them.
 
 Can I install additional VSCode extensions?
-*******************************************
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Absolutely! Any extensions you installed will be installed in your own workspace 
 and preserved.
 
 I registered on Gitpod but I still cannot see a ``Gitpod`` button in my repositories.
-*************************************************************************************
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Head to https://gitpod.io/integrations and make sure you are logged in. 
 Hover over GitHub and click on the three buttons that appear on the right. 
@@ -232,14 +232,14 @@ and confirm the changes in the GitHub application page.
    :alt: Gitpod integrations - edit GH permissions screenshot
 
 How long does my workspace stay active if I'm not using it?
-***********************************************************
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 If you keep your workspace open in a browser tab but don't interact with it, 
 it will shut down after 30 minutes. If you close the browser tab, it will 
 shut down after 3 minutes.
 
 My terminal is blank - there is no cursor and it's completely unresponsive
-**************************************************************************
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Unfortunately this is a known-issue on Gitpod's side. You can sort this 
 issue in two ways:
@@ -254,7 +254,7 @@ issue in two ways:
    :alt: Gitpod dashboard and workspace menu screenshot
 
 I authenticated through GitHub but I still cannot commit to the repository through Gitpod. 
-******************************************************************************************
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Head to https://gitpod.io/integrations and make sure you are logged in. 
 Hover over GitHub and click on the three buttons that appear on the right. 
diff --git a/doc/source/dev/howto-docs.rst b/doc/source/dev/howto-docs.rst
index ff4a9f6d5..b30955e3e 100644
--- a/doc/source/dev/howto-docs.rst
+++ b/doc/source/dev/howto-docs.rst
@@ -252,7 +252,7 @@ existing non-indexed comment blocks.
 .. doxygenclass:: DoxyLimbo
 
 Common Doxygen Tags:
-++++++++++++++++++++
+~~~~~~~~~~~~~~~~~~~~
 
 .. note::
    For more tags/commands, please take a look at https://www.doxygen.nl/manual/commands.html
@@ -340,7 +340,7 @@ converting the documents generated by Doxygen_ into reST files.
    For more information, please check out "`Directives & Config Variables <https://breathe.readthedocs.io/en/latest/directives.html>`__"
 
 Common directives:
-++++++++++++++++++
+~~~~~~~~~~~~~~~~~~
 
 ``doxygenfunction``
 
diff --git a/doc/source/dev/howto_build_docs.rst b/doc/source/dev/howto_build_docs.rst
index 32a1f121d..02a8820c9 100644
--- a/doc/source/dev/howto_build_docs.rst
+++ b/doc/source/dev/howto_build_docs.rst
@@ -12,7 +12,7 @@ versions can be found at
 in several different formats.
 
 Development environments
-------------------------
+========================
 
 Before proceeding further it should be noted that the documentation is built with the ``make`` tool,
 which is not natively available on Windows. MacOS or Linux users can jump
@@ -22,7 +22,7 @@ for Linux (WSL) <https://docs.microsoft.com/en-us/windows/wsl/install-win10>`_.
 for a persistent local set-up.
 
 Gitpod
-^^^^^^
+~~~~~~
 Gitpod is an open-source platform that automatically creates the correct development environment right
 in your browser, reducing the need to install local development environments and deal with
 incompatible dependencies.
@@ -35,12 +35,12 @@ it is often faster to build with Gitpod. Here are the in-depth instructions for
 .. _how-todoc.prerequisites:
 
 Prerequisites
--------------
+=============
 
 Building the NumPy documentation and API reference requires the following:
 
 NumPy
-^^^^^
+~~~~~
 
 Since large parts of the main documentation are obtained from NumPy via
 ``import numpy`` and examining the docstrings, you will need to first
@@ -56,7 +56,7 @@ Alternatively, if using Python virtual environments (via e.g. ``conda``,
 new virtual environment is recommended.
 
 Dependencies
-^^^^^^^^^^^^
+~~~~~~~~~~~~
 
 All of the necessary dependencies for building the NumPy docs except for
 Doxygen_ can be installed with::
@@ -81,7 +81,7 @@ are using Linux then you can install it through your distribution package manage
    warnings during the build.
 
 Submodules
-^^^^^^^^^^
+~~~~~~~~~~
 
 If you obtained NumPy via git, also get the git submodules that contain
 additional parts required for building the documentation::
@@ -93,7 +93,7 @@ additional parts required for building the documentation::
 .. _Doxygen: https://www.doxygen.nl/index.html
 
 Instructions
-------------
+============
 
 Now you are ready to generate the docs, so write::
 
diff --git a/doc/source/dev/internals.code-explanations.rst b/doc/source/dev/internals.code-explanations.rst
index b6edd61b1..eaa629523 100644
--- a/doc/source/dev/internals.code-explanations.rst
+++ b/doc/source/dev/internals.code-explanations.rst
@@ -421,7 +421,7 @@ the 1-D loop is completed.
 
 
 One loop
-^^^^^^^^
+~~~~~~~~
 
 This is the simplest case of all. The ufunc is executed by calling the
 underlying 1-D loop exactly once. This is possible only when we have
@@ -434,7 +434,7 @@ complete.
 
 
 Strided loop
-^^^^^^^^^^^^
+~~~~~~~~~~~~
 
 When the input and output arrays are aligned and of the correct type,
 but the striding is not uniform (non-contiguous and 2-D or larger),
@@ -447,7 +447,7 @@ hardware error flags are checked after each 1-D loop is completed.
 
 
 Buffered loop
-^^^^^^^^^^^^^
+~~~~~~~~~~~~~
 
 This is the code that handles the situation whenever the input and/or
 output arrays are either misaligned or of the wrong datatype
@@ -514,7 +514,7 @@ objects have 0 and 1 elements respectively.
 
 
 Setup
-^^^^^
+~~~~~
 
 The setup function for all three methods is ``construct_reduce``.
 This function creates a reducing loop object and fills it with the
@@ -546,7 +546,7 @@ routine returns to the actual computation routine.
 
 
 :meth:`Reduce <ufunc.reduce>` 
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. index::
    triple: ufunc; methods; reduce
@@ -585,7 +585,7 @@ the loop function on chunks no greater than the user-specified
 
 
 :meth:`Accumulate <ufunc.accumulate>`
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. index::
    triple: ufunc; methods; accumulate
@@ -611,7 +611,7 @@ calling the underlying 1-D computational loop.
 
 
 :meth:`Reduceat <ufunc.reduceat>`
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. index::
    triple: ufunc; methods; reduceat
diff --git a/doc/source/f2py/buildtools/meson.rst b/doc/source/f2py/buildtools/meson.rst
index 502d3e211..7edc6722f 100644
--- a/doc/source/f2py/buildtools/meson.rst
+++ b/doc/source/f2py/buildtools/meson.rst
@@ -77,7 +77,7 @@ possible. The easiest way to solve this is to let ``f2py`` deal with it:
 
 
 Automating wrapper generation
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 A major pain point in the workflow defined above, is the manual tracking of
 inputs. Although it would require more effort to figure out the actual outputs
diff --git a/doc/source/f2py/buildtools/skbuild.rst b/doc/source/f2py/buildtools/skbuild.rst
index f1a0bf65e..0db12e7b4 100644
--- a/doc/source/f2py/buildtools/skbuild.rst
+++ b/doc/source/f2py/buildtools/skbuild.rst
@@ -29,7 +29,7 @@ We will consider the ``fib``  example from :ref:`f2py-getting-started` section.
     :language: fortran
 
 ``CMake`` modules only
-^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~
 
 Consider using the following ``CMakeLists.txt``.
 
@@ -52,7 +52,7 @@ The resulting extension can be built and loaded in the standard workflow.
 
 
 ``setuptools`` replacement
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. note::
 
diff --git a/doc/source/f2py/usage.rst b/doc/source/f2py/usage.rst
index dbd33e36e..3fae093f8 100644
--- a/doc/source/f2py/usage.rst
+++ b/doc/source/f2py/usage.rst
@@ -13,7 +13,7 @@ When used as a command-line tool, ``f2py`` has three major modes, distinguished
 by the usage of ``-c`` and ``-h`` switches.
 
 1. Signature file generation
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 To scan Fortran sources and generate a signature file, use
 
@@ -40,7 +40,7 @@ Among other options (see below), the following can be used in this mode:
     Overwrites an existing signature file.
 
 2. Extension module construction
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 To construct an extension module, use
 
@@ -91,7 +91,7 @@ Here ``<fortran files>`` may also contain signature files. Among other options
     example, try ``f2py --help-link lapack_opt``.
 
 3. Building a module
-^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~
 
 To build an extension module, use
 
@@ -203,7 +203,7 @@ To see whether F2PY generated interface performs copies of array arguments, use
 larger than ``<int>``, a message about the copying is sent to ``stderr``.
 
 Other options
-^^^^^^^^^^^^^
+~~~~~~~~~~~~~
 
   ``-m <modulename>``
     Name of an extension module. Default is ``untitled``.
diff --git a/doc/source/reference/c-api/array.rst b/doc/source/reference/c-api/array.rst
index f22b41a85..f69c2bcb1 100644
--- a/doc/source/reference/c-api/array.rst
+++ b/doc/source/reference/c-api/array.rst
@@ -162,7 +162,7 @@ and its sub-types).
 
 
 Data access
-^^^^^^^^^^^
+~~~~~~~~~~~
 
 These functions and macros provide easy access to elements of the
 ndarray from C. These work for all arrays. You may need to take care
@@ -208,7 +208,7 @@ Creating arrays
 
 
 From scratch
-^^^^^^^^^^^^
+~~~~~~~~~~~~
 
 .. c:function:: PyObject* PyArray_NewFromDescr( \
         PyTypeObject* subtype, PyArray_Descr* descr, int nd, npy_intp const* dims, \
@@ -404,7 +404,7 @@ From scratch
     to another value.
 
 From other objects
-^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~
 
 .. c:function:: PyObject* PyArray_FromAny( \
         PyObject* op, PyArray_Descr* dtype, int min_depth, int max_depth, \
@@ -805,7 +805,7 @@ Dealing with types
 
 
 General check of Python Type
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. c:function:: int PyArray_Check(PyObject *op)
 
@@ -877,7 +877,7 @@ General check of Python Type
 
 
 Data-type checking
-^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~
 
 For the typenum macros, the argument is an integer representing an
 enumerated array data type. For the array type checking macros the
@@ -1048,7 +1048,7 @@ argument must be a :c:expr:`PyObject *` that can be directly interpreted as a
 
 
 Converting data types
-^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~
 
 .. c:function:: PyObject* PyArray_Cast(PyArrayObject* arr, int typenum)
 
@@ -1268,7 +1268,7 @@ Converting data types
 
 
 User-defined data types
-^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~
 
 .. c:function:: void PyArray_InitArrFuncs(PyArray_ArrFuncs* f)
 
@@ -1321,7 +1321,7 @@ User-defined data types
    Only works for user-defined data-types.
 
 Special functions for NPY_OBJECT
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. c:function:: int PyArray_INCREF(PyArrayObject* op)
 
@@ -1399,7 +1399,7 @@ PyArray_FromAny function.
 
 
 Basic Array Flags
-^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~
 
 An ndarray can have a data segment that is not a simple contiguous
 chunk of well-behaved memory you can manipulate. It may not be aligned
@@ -1482,7 +1482,7 @@ for ``flags`` which can be any of :c:data:`NPY_ARRAY_C_CONTIGUOUS`,
 
 
 Combinations of array flags
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. c:macro:: NPY_ARRAY_BEHAVED
 
@@ -1514,7 +1514,7 @@ Combinations of array flags
 
 
 Flag-like constants
-^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~
 
 These constants are used in :c:func:`PyArray_FromAny` (and its macro forms) to
 specify desired properties of the new array.
@@ -1534,7 +1534,7 @@ specify desired properties of the new array.
 
 
 Flag checking
-^^^^^^^^^^^^^
+~~~~~~~~~~~~~
 
 For all of these macros *arr* must be an instance of a (subclass of)
 :c:data:`PyArray_Type`.
@@ -1640,7 +1640,7 @@ Array method alternative API
 
 
 Conversion
-^^^^^^^^^^
+~~~~~~~~~~
 
 .. c:function:: PyObject* PyArray_GetField( \
         PyArrayObject* self, PyArray_Descr* dtype, int offset)
@@ -1749,7 +1749,7 @@ Conversion
 
 
 Shape Manipulation
-^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~
 
 .. c:function:: PyObject* PyArray_Newshape( \
         PyArrayObject* self, PyArray_Dims* newshape, NPY_ORDER order)
@@ -1833,7 +1833,7 @@ Shape Manipulation
 
 
 Item selection and manipulation
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. c:function:: PyObject* PyArray_TakeFrom( \
         PyArrayObject* self, PyObject* indices, int axis, PyArrayObject* ret, \
@@ -2013,7 +2013,7 @@ Item selection and manipulation
 
 
 Calculation
-^^^^^^^^^^^
+~~~~~~~~~~~
 
 .. tip::
 
@@ -2173,7 +2173,7 @@ Functions
 
 
 Array Functions
-^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~
 
 .. c:function:: int PyArray_AsCArray( \
         PyObject** op, void* ptr, npy_intp* dims, int nd, \
@@ -2324,7 +2324,7 @@ Array Functions
 
 
 Other functions
-^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~
 
 .. c:function:: npy_bool PyArray_CheckStrides( \
         int elsize, int nd, npy_intp numbytes, npy_intp const* dims, \
@@ -2969,7 +2969,7 @@ Conversion Utilities
 
 
 For use with :c:func:`PyArg_ParseTuple`
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 All of these functions can be used in :c:func:`PyArg_ParseTuple` (...) with
 the "O&" format specifier to automatically convert any Python object
@@ -3097,7 +3097,7 @@ to.
    to help functions allow a different clipmode for each dimension.
 
 Other conversions
-^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~
 
 .. c:function:: int PyArray_PyIntAsInt(PyObject* op)
 
@@ -3138,7 +3138,7 @@ Miscellaneous
 
 
 Importing the API
-^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~
 
 In order to make use of the C-API from another extension module, the
 :c:func:`import_array` function must be called. If the extension module is
@@ -3209,7 +3209,7 @@ the C-API is needed then some additional steps must be taken.
           #defined to.
 
 Checking the API Version
-^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~
 
 Because python extensions are not used in the same way as usual libraries on
 most platforms, some errors cannot be automatically detected at build time or
@@ -3264,7 +3264,7 @@ extension with the lowest :c:data:`NPY_FEATURE_VERSION` as possible.
     function is added). A changed value does not always require a recompile.
 
 Internal Flexibility
-^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~
 
 .. c:function:: int PyArray_SetNumericOps(PyObject* dict)
 
@@ -3321,7 +3321,7 @@ Internal Flexibility
 
 
 Memory management
-^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~
 
 .. c:function:: char* PyDataMem_NEW(size_t nbytes)
 
@@ -3368,7 +3368,7 @@ Memory management
     Returns 0 if nothing was done, -1 on error, and 1 if action was taken.
 
 Threading support
-^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~
 
 These macros are only meaningful if :c:data:`NPY_ALLOW_THREADS`
 evaluates True during compilation of the extension module. Otherwise,
@@ -3475,7 +3475,7 @@ Group 2
 
 
 Priority
-^^^^^^^^
+~~~~~~~~
 
 .. c:macro:: NPY_PRIORITY
 
@@ -3498,7 +3498,7 @@ Priority
 
 
 Default buffers
-^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~
 
 .. c:macro:: NPY_BUFSIZE
 
@@ -3514,7 +3514,7 @@ Default buffers
 
 
 Other constants
-^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~
 
 .. c:macro:: NPY_NUM_FLOATTYPE
 
@@ -3548,7 +3548,7 @@ Other constants
 
 
 Miscellaneous Macros
-^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~
 
 .. c:function:: int PyArray_SAMESHAPE(PyArrayObject *a1, PyArrayObject *a2)
 
@@ -3610,7 +3610,7 @@ Miscellaneous Macros
 
 
 Enumerated Types
-^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~
 
 .. c:enum:: NPY_SORTKIND
 
diff --git a/doc/source/reference/c-api/dtype.rst b/doc/source/reference/c-api/dtype.rst
index 382e45dc0..642f62749 100644
--- a/doc/source/reference/c-api/dtype.rst
+++ b/doc/source/reference/c-api/dtype.rst
@@ -219,7 +219,7 @@ Defines
 -------
 
 Max and min values for integers
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 ``NPY_MAX_INT{bits}``, ``NPY_MAX_UINT{bits}``, ``NPY_MIN_INT{bits}``
     These are defined for ``{bits}`` = 8, 16, 32, 64, 128, and 256 and provide
@@ -238,7 +238,7 @@ Max and min values for integers
 
 
 Number of bits in data types
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 All ``NPY_SIZEOF_{CTYPE}`` constants have corresponding
 ``NPY_BITSOF_{CTYPE}`` constants defined. The ``NPY_BITSOF_{CTYPE}``
@@ -250,7 +250,7 @@ the available ``{CTYPE}s`` are
 
 
 Bit-width references to enumerated typenums
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 All of the numeric data types (integer, floating point, and complex)
 have constants that are defined to be a specific enumerated type
@@ -265,7 +265,7 @@ types are available.
 
 
 Integer that can hold a pointer
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The constants **NPY_INTP** and **NPY_UINTP** refer to an
 enumerated integer type that is large enough to hold a pointer on the
@@ -283,7 +283,7 @@ types.
 
 
 Boolean
-^^^^^^^
+~~~~~~~
 
 .. c:type:: npy_bool
 
@@ -292,7 +292,7 @@ Boolean
 
 
 (Un)Signed Integer
-^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~
 
 Unsigned versions of the integers can be defined by pre-pending a 'u'
 to the front of the integer name.
@@ -373,7 +373,7 @@ to the front of the integer name.
 
 
 (Complex) Floating point
-^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. c:type:: npy_half
 
@@ -408,7 +408,7 @@ that order).
 
 
 Bit-width names
-^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~
 
 There are also typedefs for signed integers, unsigned integers,
 floating point, and complex floating point types of specific bit-
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
diff --git a/doc/source/reference/routines.bitwise.rst b/doc/source/reference/routines.bitwise.rst
index 58661abc7..5bf61ed8a 100644
--- a/doc/source/reference/routines.bitwise.rst
+++ b/doc/source/reference/routines.bitwise.rst
@@ -1,5 +1,5 @@
 Binary operations
-*****************
+=================
 
 .. currentmodule:: numpy
 
diff --git a/doc/source/reference/routines.char.rst b/doc/source/reference/routines.char.rst
index 90df14125..0644263f4 100644
--- a/doc/source/reference/routines.char.rst
+++ b/doc/source/reference/routines.char.rst
@@ -1,5 +1,5 @@
 String operations
-*****************
+=================
 
 .. currentmodule:: numpy.char
 
diff --git a/doc/source/reference/routines.dual.rst b/doc/source/reference/routines.dual.rst
index 01814e9a7..18c7791d0 100644
--- a/doc/source/reference/routines.dual.rst
+++ b/doc/source/reference/routines.dual.rst
@@ -1,5 +1,5 @@
 Optionally SciPy-accelerated routines (:mod:`numpy.dual`)
-*********************************************************
+=========================================================
 
 .. automodule:: numpy.dual
 
diff --git a/doc/source/reference/routines.err.rst b/doc/source/reference/routines.err.rst
index b3a7164b9..8f5106f76 100644
--- a/doc/source/reference/routines.err.rst
+++ b/doc/source/reference/routines.err.rst
@@ -1,5 +1,5 @@
 Floating point error handling
-*****************************
+=============================
 
 .. currentmodule:: numpy
 
diff --git a/doc/source/reference/routines.io.rst b/doc/source/reference/routines.io.rst
index 3052ee1fb..2542b336f 100644
--- a/doc/source/reference/routines.io.rst
+++ b/doc/source/reference/routines.io.rst
@@ -1,7 +1,7 @@
 .. _routines.io:
 
 Input and output
-****************
+================
 
 .. currentmodule:: numpy
 
diff --git a/doc/source/reference/routines.linalg.rst b/doc/source/reference/routines.linalg.rst
index 76b7ab82c..dfdcde4ab 100644
--- a/doc/source/reference/routines.linalg.rst
+++ b/doc/source/reference/routines.linalg.rst
@@ -3,7 +3,7 @@
 .. module:: numpy.linalg
 
 Linear algebra (:mod:`numpy.linalg`)
-************************************
+====================================
 
 The NumPy linear algebra functions rely on BLAS and LAPACK to provide efficient
 low level implementations of standard linear algebra algorithms. Those
diff --git a/doc/source/reference/routines.logic.rst b/doc/source/reference/routines.logic.rst
index 7fa0cd1de..68a236605 100644
--- a/doc/source/reference/routines.logic.rst
+++ b/doc/source/reference/routines.logic.rst
@@ -1,5 +1,5 @@
 Logic functions
-***************
+===============
 
 .. currentmodule:: numpy
 
diff --git a/doc/source/reference/routines.ma.rst b/doc/source/reference/routines.ma.rst
index 1de5c1c02..d503cc243 100644
--- a/doc/source/reference/routines.ma.rst
+++ b/doc/source/reference/routines.ma.rst
@@ -1,13 +1,13 @@
 .. _routines.ma:
 
 Masked array operations
-***********************
+=======================
 
 .. currentmodule:: numpy
 
 
 Constants
-=========
+---------
 
 .. autosummary::
    :toctree: generated/
@@ -16,7 +16,7 @@ Constants
 
 
 Creation
-========
+--------
 
 From existing data
 ~~~~~~~~~~~~~~~~~~
@@ -52,7 +52,7 @@ Ones and zeros
 _____
 
 Inspecting the array
-====================
+--------------------
 
 .. autosummary::
    :toctree: generated/
@@ -91,7 +91,7 @@ Inspecting the array
 _____
 
 Manipulating a MaskedArray
-==========================
+--------------------------
 
 Changing the shape
 ~~~~~~~~~~~~~~~~~~
@@ -162,7 +162,7 @@ Joining arrays
 _____
 
 Operations on masks
-===================
+-------------------
 
 Creating a mask
 ~~~~~~~~~~~~~~~
@@ -220,7 +220,7 @@ Modifying a mask
 _____
 
 Conversion operations
-======================
+----------------------
 
 > to a masked array
 ~~~~~~~~~~~~~~~~~~~
@@ -291,7 +291,7 @@ Filling a masked array
 _____
 
 Masked arrays arithmetic
-========================
+------------------------
 
 Arithmetic
 ~~~~~~~~~~
diff --git a/doc/source/reference/routines.math.rst b/doc/source/reference/routines.math.rst
index 2a09b8d20..a454841b3 100644
--- a/doc/source/reference/routines.math.rst
+++ b/doc/source/reference/routines.math.rst
@@ -1,5 +1,5 @@
 Mathematical functions
-**********************
+======================
 
 .. currentmodule:: numpy
 
diff --git a/doc/source/reference/routines.other.rst b/doc/source/reference/routines.other.rst
index 339857409..bb0be7137 100644
--- a/doc/source/reference/routines.other.rst
+++ b/doc/source/reference/routines.other.rst
@@ -1,5 +1,5 @@
 Miscellaneous routines
-**********************
+======================
 
 .. toctree::
 
diff --git a/doc/source/reference/routines.polynomials.rst b/doc/source/reference/routines.polynomials.rst
index 6ad692e70..ea22ab75f 100644
--- a/doc/source/reference/routines.polynomials.rst
+++ b/doc/source/reference/routines.polynomials.rst
@@ -1,7 +1,7 @@
 .. _routines.polynomial:
 
 Polynomials
-***********
+===========
 
 Polynomials in NumPy can be *created*, *manipulated*, and even *fitted* using
 the :doc:`convenience classes <routines.polynomials.classes>`
diff --git a/doc/source/user/basics.indexing.rst b/doc/source/user/basics.indexing.rst
index ef32f52a8..94bab061a 100644
--- a/doc/source/user/basics.indexing.rst
+++ b/doc/source/user/basics.indexing.rst
@@ -39,7 +39,7 @@ Basic indexing
 .. _single-element-indexing:
 
 Single element indexing
-^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~
 
 Single element indexing works
 exactly like that for other standard Python sequences. It is 0-based,
@@ -95,7 +95,7 @@ that is subsequently indexed by 2.
 .. _slicing-and-striding:
 
 Slicing and striding
-^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~
 
 Basic slicing extends Python's basic concept of slicing to N
 dimensions. Basic slicing occurs when *obj* is a :class:`slice` object
@@ -226,7 +226,7 @@ concepts to remember include:
 .. _dimensional-indexing-tools:
 
 Dimensional indexing tools
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 There are some tools to facilitate the easy matching of array shapes with
 expressions and in assignments.
@@ -299,7 +299,7 @@ basic slicing that returns a :term:`view`).
    ``x[[1, 2, slice(None)]]`` will trigger basic slicing.
 
 Integer array indexing
-^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~
 
 Integer array indexing allows selection of arbitrary items in the array
 based on their *N*-dimensional index. Each integer array represents a number
@@ -475,7 +475,7 @@ triple of RGB values is associated with each pixel location.
 .. _boolean-indexing:
 
 Boolean array indexing
-^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~
 
 This advanced indexing occurs when *obj* is an array object of Boolean
 type, such as may be returned from comparison operators. A single
@@ -606,7 +606,7 @@ with four True elements to select rows from a 3-D array of shape
 .. _combining-advanced-and-basic-indexing:
 
 Combining advanced and basic indexing
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 When there is at least one slice (``:``), ellipsis (``...``) or :const:`newaxis`
 in the index (or the array has more dimensions than there are advanced indices),
diff --git a/doc/source/user/basics.subclassing.rst b/doc/source/user/basics.subclassing.rst
index 7b97abab7..e075a2b3f 100644
--- a/doc/source/user/basics.subclassing.rst
+++ b/doc/source/user/basics.subclassing.rst
@@ -5,7 +5,7 @@ Subclassing ndarray
 *******************
 
 Introduction
-------------
+============
 
 Subclassing ndarray is relatively simple, but it has some complications
 compared to other Python objects.  On this page we explain the machinery
@@ -13,7 +13,7 @@ that allows you to subclass ndarray, and the implications for
 implementing a subclass.
 
 ndarrays and object creation
-============================
+----------------------------
 
 Subclassing ndarray is complicated by the fact that new instances of
 ndarray classes can come about in three different ways.  These are:
@@ -32,7 +32,7 @@ due to the mechanisms numpy has to support these latter two routes of
 instance creation.
 
 When to use subclassing
-=======================
+-----------------------
 
 Besides the additional complexities of subclassing a NumPy array, subclasses
 can run into unexpected behaviour because some functions may convert the
@@ -77,7 +77,7 @@ which uses a dual approach of both subclassing and interoperability protocols.
 .. _view-casting:
 
 View casting
-------------
+============
 
 *View casting* is the standard ndarray mechanism by which you take an
 ndarray of any subclass, and return a view of the array as another
@@ -96,7 +96,7 @@ ndarray of any subclass, and return a view of the array as another
 .. _new-from-template:
 
 Creating new from template
---------------------------
+==========================
 
 New instances of an ndarray subclass can also come about by a very
 similar mechanism to :ref:`view-casting`, when numpy finds it needs to
@@ -120,7 +120,7 @@ such as copying arrays (``c_arr.copy()``), creating ufunc output arrays
 ``c_arr.mean()``).
 
 Relationship of view casting and new-from-template
---------------------------------------------------
+==================================================
 
 These paths both use the same machinery.  We make the distinction here,
 because they result in different input to your methods.  Specifically,
@@ -131,7 +131,7 @@ instance, allowing you - for example - to copy across attributes that
 are particular to your subclass.
 
 Implications for subclassing
-----------------------------
+============================
 
 If we subclass ndarray, we need to deal not only with explicit
 construction of our array type, but also :ref:`view-casting` or
@@ -148,7 +148,7 @@ allow subclasses to clean up after the creation of views and new
 instances from templates.
 
 A brief Python primer on ``__new__`` and ``__init__``
-=====================================================
+-----------------------------------------------------
 
 ``__new__`` is a standard Python method, and, if present, is called
 before ``__init__`` when we create a class instance. See the `python
@@ -239,7 +239,7 @@ why not call ``obj = subdtype.__new__(...`` then?  Because we may not
 have a ``__new__`` method with the same call signature).
 
 The role of ``__array_finalize__``
-==================================
+----------------------------------
 
 ``__array_finalize__`` is the mechanism that numpy provides to allow
 subclasses to handle the various ways that new instances get created.
@@ -338,7 +338,7 @@ defaults for new object attributes, among other tasks.
 This may be clearer with an example.
 
 Simple example - adding an extra attribute to ndarray
------------------------------------------------------
+=====================================================
 
 .. testcode::
 
@@ -416,7 +416,7 @@ formed ndarray from the usual numpy calls to ``np.array`` and return an
 object.
 
 Slightly more realistic example - attribute added to existing array
--------------------------------------------------------------------
+===================================================================
 
 Here is a class that takes a standard ndarray that already exists, casts
 as our type, and adds an extra attribute.
@@ -459,7 +459,7 @@ So:
 .. _array-ufunc:
 
 ``__array_ufunc__`` for ufuncs
-------------------------------
+==============================
 
   .. versionadded:: 1.13
 
@@ -599,7 +599,7 @@ pass on to ``A.__array_ufunc__``, the ``super`` call in ``A`` would go to
 .. _array-wrap:
 
 ``__array_wrap__`` for ufuncs and other functions
--------------------------------------------------
+=================================================
 
 Prior to numpy 1.13, the behaviour of ufuncs could only be tuned using
 ``__array_wrap__`` and ``__array_prepare__``. These two allowed one to
@@ -704,7 +704,7 @@ Like ``__array_wrap__``, ``__array_prepare__`` must return an ndarray or
 subclass thereof or raise an error.
 
 Extra gotchas - custom ``__del__`` methods and ndarray.base
------------------------------------------------------------
+===========================================================
 
 One of the problems that ndarray solves is keeping track of memory
 ownership of ndarrays and their views.  Consider the case where we have
@@ -742,7 +742,7 @@ how this can work, have a look at the ``memmap`` class in
 ``numpy.core``.
 
 Subclassing and Downstream Compatibility
-----------------------------------------
+========================================
 
 When sub-classing ``ndarray`` or creating duck-types that mimic the ``ndarray``
 interface, it is your responsibility to decide how aligned your APIs will be
diff --git a/doc/source/user/c-info.beyond-basics.rst b/doc/source/user/c-info.beyond-basics.rst
index 04ca83489..a1523e514 100644
--- a/doc/source/user/c-info.beyond-basics.rst
+++ b/doc/source/user/c-info.beyond-basics.rst
@@ -459,7 +459,7 @@ Some special methods and attributes are used by arrays in order to
 facilitate the interoperation of sub-types with the base ndarray type.
 
 The __array_finalize\__ method
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. attribute:: ndarray.__array_finalize__
 
@@ -495,7 +495,7 @@ The __array_finalize\__ method
 
 
 The __array_priority\__ attribute
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. attribute:: ndarray.__array_priority__
 
@@ -513,7 +513,7 @@ The __array_priority\__ attribute
    the return output.
 
 The __array_wrap\__ method
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. attribute:: ndarray.__array_wrap__