libsemigroups · james-d-mitchell · Jun 16, 2025 · Jun 16, 2025 · Jun 16, 2025 · Jun 16, 2025
diff --git a/docs/source/data-structures/constants/index.rst b/docs/source/data-structures/constants/index.rst
@@ -0,0 +1,46 @@
+..
+    Copyright (c) 2024 Joseph Edwards
+
+    Distributed under the terms of the GPL license version 3.
+
+    The full license is in the file LICENSE, distributed with this software.
+
+.. currentmodule:: _libsemigroups_pybind11
+
+Constants
+=========
+
+This page describes some of the constants used in ``libsemigroups_pybind11``.
+
+
+.. autodata:: UNDEFINED
+
+    This variable is used to indicate that a value is undefined.
+    :any:`UNDEFINED` is comparable with any integral value (signed or
+    unsigned) or constant via ``==`` and ``!=`` but not via ``<`` or ``>``.
+
+
+.. autodata:: POSITIVE_INFINITY
+
+    This variable of type :class:`_libsemigroups_pybind11.PositiveInfinity`
+    represents :math:`\infty`. :any:`POSITIVE_INFINITY` is comparable via
+    ``==``, ``!=``, ``<``, ``>`` with any integral value (signed or
+    unsigned) and with :any:`NEGATIVE_INFINITY`, and is comparable to any
+    other constant via ``==`` and ``!=``, but not by ``<`` and ``>``.
+
+
+.. autodata:: LIMIT_MAX
+
+    This variable represents the maximum value that certain function
+    parameters can have. :any:`LIMIT_MAX` is comparable via ``==``, ``!=``,
+    ``<``, ``>`` with any integral value (signed or unsigned), and is
+    comparable to any other constant via ``==`` and ``!=``, but not by ``<``
+    and ``>``.
+
+
+.. autodata:: NEGATIVE_INFINITY
+
+    This variable represents :math:`-\infty`. :any:`NEGATIVE_INFINITY` is
+    comparable via ``==``, ``!=``, ``<``, ``>`` with any signed integral
+    value and with :any:`POSITIVE_INFINITY`, and is comparable to any other
+    constant via ``==`` and ``!=``.
diff --git a/docs/source/data-structures/elements/matrix/matrix.rst b/docs/source/data-structures/elements/matrix/matrix.rst
@@ -13,14 +13,6 @@ The Matrix class
 .. autoclass:: Matrix
     :doc-only:
 
-MatrixKind
-----------
-
-.. TODO move MatrixKind to the "enums" page when it exists
-
-.. autoclass:: MatrixKind
-    :show-inheritance:
-
 Contents
 --------
 

diff --git a/docs/source/data-structures/misc/types.rst → ...data-structures/enums/congruence-kind.rst b/docs/source/data-structures/misc/types.rst → ...data-structures/enums/congruence-kind.rst
@@ -10,10 +10,17 @@
 The congruence_kind enum
 ========================
 
-This page describes the enum class ``congruence_kind`` in
+This page describes the enum class :any:`congruence_kind` in
 ``libsemigroups_pybind11`` for representing the whether a congruence is one- or
 two-sided.
 
+.. seealso:: 
+
+    * :any:`Congruence`,
+    * :any:`Kambites`,
+    * :any:`KnuthBendix`,
+    * :any:`ToddCoxeter`.
+
 Full API
 --------
 

diff --git a/docs/source/data-structures/enums/index.rst b/docs/source/data-structures/enums/index.rst
@@ -0,0 +1,22 @@
+..
+    Copyright (c) 2025 Joseph Edwards
+
+    Distributed under the terms of the GPL license version 3.
+
+    The full license is in the file LICENSE, distributed with this software.
+
+Enums
+=====
+
+In this section, we describe the :any:`Enum <enum.Enum>` classes available in
+``libsemigroups_pybind11``.
+
+.. toctree::
+    :maxdepth: 1
+
+    congruence-kind
+    matrix-kind
+    order
+    side
+    tril
+
diff --git a/docs/source/data-structures/enums/matrix-kind.rst b/docs/source/data-structures/enums/matrix-kind.rst
@@ -0,0 +1,24 @@
+..
+    Copyright (c) 2025, Joseph Edwards
+
+    Distributed under the terms of the GPL license version 3.
+
+    The full license is in the file LICENSE, distributed with this software.
+
+.. currentmodule:: libsemigroups_pybind11
+
+The MatrixKind enum
+===================
+
+This page describes the enum class :any:`MatrixKind` in
+``libsemigroups_pybind11`` for representing the semiring of elements in a
+matrix.
+
+.. seealso::
+
+    :any:`Matrix`.
+
+Full API
+--------
+
+.. autoclass:: MatrixKind
diff --git a/docs/source/data-structures/enums/order.rst b/docs/source/data-structures/enums/order.rst
@@ -0,0 +1,19 @@
+..
+    Copyright (c) 2025, Joseph Edwards
+
+    Distributed under the terms of the GPL license version 3.
+
+    The full license is in the file LICENSE, distributed with this software.
+
+.. currentmodule:: libsemigroups_pybind11
+
+The Order enum
+===============
+
+This page describes the enum class :any:`Order` in ``libsemigroups_pybind11``
+for representing the order of words.
+
+Full API
+--------
+
+.. autoclass:: Order
diff --git a/docs/source/main-algorithms/action/side.rst → docs/source/data-structures/enums/side.rst b/docs/source/main-algorithms/action/side.rst → docs/source/data-structures/enums/side.rst
@@ -10,8 +10,13 @@
 The side enum
 =============
 
-This page describes the enum class ``side`` in ``libsemigroups_pybind11`` for
-representing whether an action is a left or a right action.
+This page describes the enum class :py:class:`side` in
+``libsemigroups_pybind11`` for representing whether an action is a left or a
+right action.
+
+.. seealso:: 
+
+    :any:`Action`.
 
 Full API
 --------

diff --git a/docs/source/data-structures/misc/tril.rst → docs/source/data-structures/enums/tril.rst b/docs/source/data-structures/misc/tril.rst → docs/source/data-structures/enums/tril.rst
@@ -10,8 +10,9 @@
 The tril enum
 =============
 
-This page describes the enum class ``tril`` in ``libsemigroups_pybind11`` for
-representing values that can either be true, false, or not currently known.
+This page describes the enum class :py:class:`tril` in
+``libsemigroups_pybind11`` for representing values that can either be true,
+false, or not currently known.
 
 Full API
 --------

diff --git a/docs/source/data-structures/misc/constants.rst b/docs/source/data-structures/misc/constants.rst
diff --git a/docs/source/data-structures/misc/index.rst b/docs/source/data-structures/misc/index.rst
@@ -14,13 +14,8 @@ In this section we describe some miscellaneous functionality in
 .. toctree::
     :maxdepth: 1
 
-    constants
     obvinf
     libsemigroups-error
-    runner
-    reporter
-    tril
-    types
 
 ..
     ukkonen/index
diff --git a/docs/source/data-structures/order/index.rst b/docs/source/data-structures/order/index.rst
@@ -10,25 +10,26 @@
 Orders
 ======
 
-This page contains the documentation for several classes and functions for
-comparing words or strings with respect to certain reduction orderings.
+This page contains the documentation for several functions for comparing words
+or strings with respect to certain reduction orderings.
+
+.. seealso::
+
+    :any:`Order`.
 
 Contents
 --------
 
 .. autosummary::
     :signatures: short
 
-    Order
     lexicographical_compare
     recursive_path_compare
     shortlex_compare
 
 Full API
 --------
 
-.. autoclass:: Order
-
 .. autofunction:: lexicographical_compare
 
 .. autofunction:: recursive_path_compare

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -44,11 +44,8 @@ How to use it
 
 See the installation instructions:
 
-.. toctree::
-    :maxdepth: 1
-
-    install
-    changelog
+    * :doc:`install`
+    * :doc:`changelog`
 
 The structure of the module
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -102,17 +99,38 @@ defined upon. These may appear in error messages. For example:
     <BLANKLINE>
     Invoked with: <AhoCorasick with 1 node>, False
 
-The authors of ``libsemigroups_pybind11`` have gone to a lot of effort to
-try and make error messages clear, specific and intelligible; however, if there
-you encounter any errors with unclear messages, please raise this on the
+The :doc:`authors <authors>` of ``libsemigroups_pybind11`` have gone to a lot of
+effort to try and make error messages clear, specific and intelligible; however,
+if there you encounter any errors with unclear messages, please raise this on
+the
 `issue tracker <https://github.com/libsemigroups/libsemigroups_pybind11/issues>`_.
 
+Further Info
+------------
+
+For additional information about ``libsemigroups_pybind11``, see the following:
+
+    * :doc:`authors`
+    * :doc:`biblio`
+
+.. toctree::
+    :caption: Package Info
+    :maxdepth: 1
+    :hidden:
+
+    install
+    changelog
+    authors
+    biblio
+
 .. toctree::
     :caption: Data Structures
     :hidden:
 
     data-structures/adapters/index
+    data-structures/constants/index
     data-structures/elements/index
+    data-structures/enums/index
     data-structures/misc/index
     data-structures/order/index
     data-structures/presentations/index
@@ -129,6 +147,7 @@ you encounter any errors with unclear messages, please raise this on the
 
     main-algorithms/action/index
     main-algorithms/congruence/index
+    main-algorithms/core-classes/index
     main-algorithms/froidure-pin/index
     main-algorithms/kambites/index
     main-algorithms/knuth-bendix/index
@@ -139,14 +158,3 @@ you encounter any errors with unclear messages, please raise this on the
     main-algorithms/stephen/index
     main-algorithms/todd-coxeter/index
 
-.. toctree::
-    :caption: Bibliography
-    :hidden:
-
-    biblio
-
-.. toctree::
-    :caption: Further info
-    :maxdepth: 1
-
-    authors
diff --git a/docs/source/main-algorithms/action/index.rst b/docs/source/main-algorithms/action/index.rst
@@ -13,10 +13,13 @@ Actions
 This page contains links to the documentation for the classes in
 ``libsemigroups_pybind11`` for semigroup actions.
 
+.. seealso:: 
+
+    :any:`side`.
+
 .. toctree::
     :maxdepth: 1
 
     action
     leftaction
     rightaction
-    side
diff --git a/docs/source/main-algorithms/core-classes/index.rst b/docs/source/main-algorithms/core-classes/index.rst
@@ -0,0 +1,25 @@
+..
+    Copyright (c) 2025 Joseph Edwards
+
+    Distributed under the terms of the GPL license version 3.
+
+    The full license is in the file LICENSE, distributed with this software.
+
+Core classes
+============
+
+Many of the classes in ``libsemigroups_pybind11`` implement algorithms, and
+hence are runnable. During the running of these algorithms, it is often
+desirable to report the state of the algorithm. Therefore, the classes
+:any:`Runner` and :any:`Reporter` exist to provide common functions to many
+classes that implement the main algorithms.
+
+Documentation for these, and associated, classes can be found on the following
+pages. 
+
+.. toctree::
+    :maxdepth: 1
+
+    reporter
+    report-guard
+    runner