Add spec index entries based on .tex index entries (chapel-lang#24632)

This PR adds `.. index::` directives to the .rst language specification
based upon `\index` entries that were present in the .tex version. All
directives added here use the `single:` format.

Note that the sphinx index only supports 2-level nesting. That meant
adjusting some of the more deeply nested cases that we had in the .tex
version.

This PR also adds a few index entries that were noticeably absent from
the .tex version (since the language specification had evolved since
then).

See also [the sphinx documentation about index
directives](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#index-generating-markup)

Reviewed by @lydia-duncan - thanks!

- [x] comm=none testing

doc/rst/language/spec/arrays.rst

@@ -1,5 +1,7 @@
 .. default-domain:: chpl
 
+.. index::
+   single: arrays
 .. _Chapter-Arrays:
 
 ======
@@ -20,6 +22,10 @@ Users must take care when applying operations to arrays and domains
 concurrently from distinct tasks. For more information see
 :ref:`the Parallel Safety section for domains <Domain_and_Array_Parallel_Safety>`.
 
+.. index::
+   single: arrays; types
+   single: arrays; domain type
+   single: arrays; element type
 .. _Array_Types:
 
 Array Types
@@ -116,6 +122,11 @@ An array’s element type can be referred to using the member symbol
       real(64)
       real(64)
 
+.. index::
+   single: arrays; values
+   single: arrays; initialization
+   single: initialization; arrays
+   single: arrays; literals
 .. _Array_Values:
 
 Array Values
@@ -141,6 +152,9 @@ corresponding to the underlying domain which defines its indices.
      rectangular-array-literal
      associative-array-literal
 
+.. index::
+   pair: rectangular arrays; literals
+   seealso: arrays; rectangular arrays
 .. _Rectangular_Array_Literals:
 
 Rectangular Array Literals
@@ -230,9 +244,16 @@ procedure with an implicit return type (see
    arrays whose elements are themselves 1D arrays.
 
 
+.. index::
+   single: rectangular arrays; default values
+
 A rectangular array’s default value is an array in which each element
 is initialized to the default value of the element type.
 
+.. index::
+   pair: associative arrays; literals
+   seealso: arrays; associative arrays
+
 .. _Associative_Array_Literals:
 
 Associative Array Literals
@@ -299,6 +320,8 @@ of values in the listing also match. A trailing comma is allowed.
       (16, sixteen)
       (3, three)
 
+.. index::
+   single: arrays; runtime representation
 .. _Array_Runtime_Representation:
 
 Runtime Representation of Array Values
@@ -309,6 +332,8 @@ domain’s distribution. Through this mechanism, users can reason about and
 control the runtime representation of an array’s elements. See
  :ref:`Chapter-Domain_Maps` for more details.
 
+.. index::
+   pair: arrays; indexing
 .. _Array_Indexing:
 
 Array Indexing
@@ -353,6 +378,8 @@ Except for associative arrays, if an array is indexed using an index
 that is not part of its domain’s index set, the reference is considered
 out-of-bounds and a runtime error will occur, halting the program.
 
+.. index::
+   pair: rectangular arrays; indexing
 .. _Rectangular_Array_Indexing:
 
 Rectangular Array Indexing
@@ -442,6 +469,8 @@ the array.
    even for one-dimensional arrays because one-dimensional arrays can be
    indexed into by 1-tuples.
 
+.. index::
+   pair: associative arrays; indexing
 .. _Associative_Array_Indexing:
 
 Associative Array Indexing
@@ -476,6 +505,8 @@ Indices can be added to associative arrays through the array’s domain.
       A["b"] = 2;
       var x = A["a"];
 
+.. index::
+   pair: arrays; iteration
 .. _Iteration_over_Arrays:
 
 Iteration over Arrays
@@ -504,6 +535,8 @@ is semantically equivalent to:
 The iterator variable for an array iteration is a reference to the array
 element type.
 
+.. index::
+   pair: arrays; assignment
 .. _Array_Assignment:
 
 Array Assignment
@@ -653,6 +686,8 @@ array of booleans.  To get a single result use the ``equals`` method instead.
   arr1.equals(arr2) // compare entire arrays resulting in a single boolean
 
 
+.. index::
+   pair: arrays; slicing
 .. _Array_Slicing:
 
 Array Slicing
@@ -718,6 +753,9 @@ corresponding to the slicing domain’s index set.
    assigns the elements in the interior of ``B`` to the elements in the
    interior of ``A``.
 
+.. index::
+   single: arrays; slicing
+   pair: slicing; rectangular arrays
 .. _Rectangular_Array_Slicing:
 
 Rectangular Array Slicing
@@ -738,6 +776,8 @@ domain by the specified ranges to create a subdomain as described
 in :ref:`Array_Slicing` and then using that subdomain to slice
 the array.
 
+.. index::
+   pair: arrays; rank change slicing
 .. _Rectangular_Array_Slicing_With_Rank_Change:
 
 Rectangular Array Slicing with a Rank Change
@@ -781,6 +821,9 @@ passed in to take the slice.
    the slice ``A[1..n, 1]`` is a one-dimensional array whose elements
    are the first column of ``A``.
 
+.. index::
+   pair: arrays; count operator
+   single: operators;# (on arrays)
 .. _Count_Operator_Arrays:
 
 Count Operator
@@ -792,13 +835,18 @@ an integer in the case of a 1D array). The operator is equivalent to
 applying the ``#`` operator to the array’s domain and using the result
 to slice the array as described in Section :ref:`Rectangular_Array_Slicing`.
 
+.. index::
+   pair: arrays; swap operator
+   single: operators;<=> (on arrays)
 .. _Array_Swap_Operator:
 
 Swap operator ``<=>``
 -------------------------------
 The ``<=>`` operator can be used to swap the contents of two arrays
 with the same shape.
 
+.. index::
+   pair: arrays; arguments
 .. _Array_Arguments_To_Functions:
 
 Array Arguments to Functions
@@ -818,6 +866,8 @@ signature, the domain of the actual argument must represent the same
 index set. If the formal array’s domain was declared using an explicit
 distribution, the actual array’s domain must use an equivalent distribution.
 
+.. index::
+   pair: arrays; promotion
 .. _Array_Promotion_of_Scalar_Functions:
 
 Array Promotion of Scalar Functions
@@ -860,6 +910,8 @@ function as defined in :ref:`Promotion`.
    if ``A``, ``B``, and ``C`` are arrays, this code assigns each element
    in ``A`` the element-wise sum of the elements in ``B`` and ``C``.
 
+.. index::
+   pair: arrays; returning
 .. _Returning_Arrays_from_Functions:
 
 Returning Arrays from Functions
@@ -871,6 +923,8 @@ intents can be used to return a reference to an array.
 Similarly to array arguments, the element type and/or domain of an array
 return type can be omitted.
 
+.. index::
+   single: arrays; sparse
 .. _Sparse_Arrays:
 
 Sparse Arrays
@@ -937,6 +991,9 @@ element type by assigning to a pseudo-field named ``IRV`` in the array.
 
       sparse-error.chpl:9: error: halt reached - attempting to assign a 'zero' value in a sparse array at index (1, 5)
 
+.. index::
+   single: domains; association with arrays
+   single: arrays; association with domains
 .. _Association_of_Arrays_to_Domains:
 
 Association of Arrays to Domains
@@ -1026,6 +1083,9 @@ will halt with an error message.
 For the ``+=`` and ``|=`` operators, the value from ``B`` will overwrite
 the existing value in ``A`` when indices overlap.
 
+.. index::
+   pair: arrays; predefined functions
+   seealso: functions; predefined functions
 .. _Predefined_Functions_and_Methods_on_Arrays:
 
 Predefined Routines on Arrays

doc/rst/language/spec/bytes.rst

@@ -1,6 +1,9 @@
 
 .. default-domain:: chpl
 
+.. index::
+   single: bytes
+   single: types; bytes
 .. _Chapter-Bytes:
 
 =====