Add LibsemigroupsError to the doc

docs/source/data-structures/misc/index.rst

@@ -15,6 +15,7 @@ In this section we describe some miscellaneous functionality in
 
    constants
    obvinf
+   libsemigroups-error
    runner
    reporter
 

docs/source/data-structures/misc/libsemigroups-error.rst

@@ -0,0 +1,39 @@
+.. 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
+
+LibsemigroupsError
+==================
+
+This page describes the custom error type used in ``libsemigroups_pybind11``,
+namely ``LibsemigroupsError``.
+
+.. autoclass:: LibsemigroupsError
+
+    All exceptions thrown by ``libsemigroups_pybind11`` are of the type
+    :any:`LibsemigroupsError`. This is an error type derived from
+    :any:`RuntimeError`.
+
+    .. doctest:: python
+
+        >>> from libsemigroups_pybind11 import FroidurePin, Perm
+        >>> gens = [Perm([3, 0, 1, 2]), Perm([1, 2, 0, 3]), Perm([2, 1, 0, 3])]
+        >>> S = FroidurePin(gens[0])
+        >>> S.add_generators(gens[1:])
+        <partially enumerated FroidurePin with 3 generators, 3 elements, Cayley graph ⌀ 1, & 0 rules>
+
+        >>> S.generator(3) # Bad: there are only three generators
+        Traceback (most recent call last):
+            ...
+        _libsemigroups_pybind11.LibsemigroupsError: generator index out of bounds, expected value in [0, 3), got 3
+
+    .. note::
+
+        If you believe your code is incorrectly throwing a
+        :any:`LibsemigroupsError`, or isn't throwing a :any:`LibsemigroupsError`
+        but you think it should, please let us known by opening an issue on the
+        `issue tracker <https://github.com/libsemigroups/libsemigroups_pybind11/issues>`_.

src/main.cpp

@@ -121,7 +121,7 @@ namespace libsemigroups {
     m.attr("LIBSEMIGROUPS_EIGEN_ENABLED")
         = static_cast<bool>(LIBSEMIGROUPS_EIGEN_ENABLED);
 #else
-    m.attr("LIBSEMIGROUPS_EIGEN_ENABLED") = false;
+    m.attr("LIBSEMIGROUPS_EIGEN_ENABLED")   = false;
 #endif
 
 #ifdef LIBSEMIGROUPS_HPCOMBI_ENABLED
@@ -131,6 +131,28 @@ namespace libsemigroups {
     m.attr("LIBSEMIGROUPS_HPCOMBI_ENABLED") = false;
 #endif
 
+    ////////////////////////////////////////////////////////////////////////
+    // Exceptions
+    ////////////////////////////////////////////////////////////////////////
+
+    // TODO this doesn't seem to properly catch all LibsemigroupsExceptions,
+    // particularly on macOS. This may have been resolved in pybind11 2.12.0
+    static py::exception<LibsemigroupsException> exc(
+        m, "LibsemigroupsError", PyExc_RuntimeError);
+    py::register_exception_translator([](std::exception_ptr p) {
+      try {
+        if (p) {
+          std::rethrow_exception(p);
+        }
+      } catch (LibsemigroupsException const& e) {
+        exc(formatted_error_message(e).c_str());
+      } catch (py::stop_iteration const& e) {
+        throw e;
+      } catch (std::runtime_error const& e) {
+        exc(formatted_error_message(e).c_str());
+      }
+    });
+
     ////////////////////////////////////////////////////////////////////////
     // Classes
     ////////////////////////////////////////////////////////////////////////
@@ -174,7 +196,7 @@ namespace libsemigroups {
 #ifdef VERSION_INFO
     m.attr("__version__") = VERSION_INFO;
 #else
-    m.attr("__version__") = "dev";
+    m.attr("__version__")                   = "dev";
 #endif
 
     ////////////////////////////////////////////////////////////////////////
@@ -404,28 +426,6 @@ default.
     m.def("error_message_with_prefix",
           py::overload_cast<bool>(&error_message_with_prefix));
 
-    ////////////////////////////////////////////////////////////////////////
-    // Exceptions
-    ////////////////////////////////////////////////////////////////////////
-
-    // TODO this doesn't seem to properly catch all LibsemigroupsExceptions,
-    // particularly on macOS. This may have been resolved in pybind11 2.12.0
-    static py::exception<LibsemigroupsException> exc(
-        m, "LibsemigroupsError", PyExc_RuntimeError);
-    py::register_exception_translator([](std::exception_ptr p) {
-      try {
-        if (p) {
-          std::rethrow_exception(p);
-        }
-      } catch (LibsemigroupsException const& e) {
-        exc(formatted_error_message(e).c_str());
-      } catch (py::stop_iteration const& e) {
-        throw e;
-      } catch (std::runtime_error const& e) {
-        exc(formatted_error_message(e).c_str());
-      }
-    });
-
     ////////////////////////////////////////////////////////////////////////
     // Things so short they don't merit their own file
     ////////////////////////////////////////////////////////////////////////