doc: more properly say that Runners don't subclass Runner (#286)

Author: james-d-mitchell

docs/source/_static/runner_non_inherit.rst

@@ -0,0 +1,6 @@
+.. important:: 
+
+   The class |name| has all the methods of the :any:`Runner` class but, for
+   boring technical reasons, is not a subclass of :any:`Runner`. If ``thing`` is
+   an instance of |name|, then you can use ``thing`` as if it were an instance
+   of :any:`Runner` but ``isinstance(thing, Runner)`` will return ``False``.

src/action.cpp

@@ -78,10 +78,11 @@ In this documentation we refer to:
 * ``Side`` -- the side of the action (if it is a left or a right action).
 
 .. seealso::
+  :any:`LeftAction`, :any:`RightAction`, and :any:`Runner`.
 
-  * :any:`LeftAction`
-  * :any:`RightAction`
-  * :any:`Runner`
+.. |name| replace:: :any:`Action`
+
+.. include:: ../../_static/runner_non_inherit.rst
 
 .. doctest::
 

src/cong.cpp

@@ -52,6 +52,10 @@ individual algorithms, such as :any:`Kambites`,
 
 .. seealso::  :any:`Runner`, :any:`congruence_kind`, and :any:`tril`.
 
+.. |name| replace:: :any:`Congruence`
+
+.. include:: ../../_static/runner_non_inherit.rst
+
 .. doctest::
 
     >>> from libsemigroups_pybind11 import (Presentation, presentation, Congruence,

src/froidure-pin.cpp

@@ -401,7 +401,7 @@ full enumeration is triggered by calls to this function.
           pyclass_name.c_str(),
           // To change the top-level signature of a class, :sig=...: should be
           // specified here in the class docstring. This is most likely the
-          // desired behaiour if a constructor is not overloaded.
+          // desired behaviour if a constructor is not overloaded.
           // If the constructor is overloaded and the signature of an
           // individual overload is to be changed, :sig=...: should be
           // specified in the docstring of that py::init function.
@@ -427,6 +427,10 @@ the left and right Cayley graphs :any:`FroidurePin.left_cayley_graph` and
 terminating presentation :any:`froidure_pin.rules` for the semigroup is known.
 
 .. seealso:: :any:`Runner`.
+
+.. |name| replace:: :any:`FroidurePin`
+
+.. include:: ../../_static/runner_non_inherit.rst
 )pbdoc");
 
       bind_froidure_pin_core(m, thing);

src/kambites.cpp

@@ -54,7 +54,14 @@ computing normal forms. Note that a :any:`Kambites` instance represents a
 congruence on the free monoid or semigroup containing the rules of a
 presentation used to construct the instance, and the
 :any:`Kambites.generating_pairs`. As such generating pairs or rules are
-interchangeable in the context of :any:`Kambites` objects.)pbdoc");
+interchangeable in the context of :any:`Kambites` objects.
+
+.. seealso:: :any:`Runner`.
+
+.. |name| replace:: :any:`Kambites`
+
+.. include:: ../../_static/runner_non_inherit.rst
+)pbdoc");
 
       ////////////////////////////////////////////////////////////////////////
       // Things from cong-common.hpp . . .

src/knuth-bendix.cpp

@@ -54,24 +54,30 @@ semigroup.
 :any:`KnuthBendix` inherits from :any:`Runner` and has the
 nested class :any:`KnuthBendix.options`.
 
- .. doctest::
+.. seealso:: :any:`Runner`.
 
-    >>> from libsemigroups_pybind11 import (KnuthBendix, Presentation,
-    ... presentation, congruence_kind)
-    >>> p = Presentation("abc")
-    >>> presentation.add_rule(p, "aaaa", "a")
-    >>> presentation.add_rule(p, "bbbb", "b")
-    >>> presentation.add_rule(p, "cccc", "c")
-    >>> presentation.add_rule(p, "abab", "aaa")
-    >>> presentation.add_rule(p, "bcbc", "bbb")
-    >>> kb = KnuthBendix(congruence_kind.twosided, p)
-    >>> not kb.confluent()
-    True
-    >>> kb.run()
-    >>> kb.number_of_active_rules()
-    31
-    >>> kb.confluent()
-    True
+.. |name| replace:: :any:`KnuthBendix`
+
+.. include:: ../../_static/runner_non_inherit.rst
+
+.. doctest::
+
+   >>> from libsemigroups_pybind11 import (KnuthBendix, Presentation,
+   ... presentation, congruence_kind)
+   >>> p = Presentation("abc")
+   >>> presentation.add_rule(p, "aaaa", "a")
+   >>> presentation.add_rule(p, "bbbb", "b")
+   >>> presentation.add_rule(p, "cccc", "c")
+   >>> presentation.add_rule(p, "abab", "aaa")
+   >>> presentation.add_rule(p, "bcbc", "bbb")
+   >>> kb = KnuthBendix(congruence_kind.twosided, p)
+   >>> not kb.confluent()
+   True
+   >>> kb.run()
+   >>> kb.number_of_active_rules()
+   31
+   >>> kb.confluent()
+   True
 )pbdoc");
 
       // __repr__ is implemented in KnuthBendixImpl_

src/konieczny.cpp

@@ -55,7 +55,12 @@ function is :any:`Runner.run`, which implements Konieczny's Algorithm. If
 the size, partial order of :math:`\mathscr{D}`-classes, and frames for each
 :math:`\mathscr{D}`-class are known.
 
-.. seealso:: :any:`Konieczny.DClass`)pbdoc");
+.. seealso:: :any:`Konieczny.DClass` and :any:`Runner`.
+
+.. |name| replace:: :any:`Konieczny`
+
+.. include:: ../../_static/runner_non_inherit.rst
+)pbdoc");
       thing.def("__repr__", [](Konieczny_ const& self) {
         return to_human_readable_repr(self);
       });

src/libsemigroups_pybind11/action.py

@@ -180,9 +180,7 @@ class Action(_CxxWrapper):  # pylint: disable=missing-class-docstring
     ########################################################################
 
     # pylint: disable=redefined-outer-name
-    def __init__(
-        self: _Self, *args, generators=None, seeds=None, func=None, side=None
-    ) -> None:
+    def __init__(self: _Self, *args, generators=None, seeds=None, func=None, side=None) -> None:
         """
         :sig=(self: Action, generators=None, seeds=None, func=None, side=None) -> None:
 
@@ -214,9 +212,7 @@ def __init__(
         if _to_cxx(self) is not None:
             return
         if len(args) != 0:
-            raise TypeError(
-                f"expected 0 positional arguments, but found {len(args)}"
-            )
+            raise TypeError(f"expected 0 positional arguments, but found {len(args)}")
         if not isinstance(generators, list):
             raise TypeError(
                 "expected the keyword argument 'generators' to be "
@@ -279,9 +275,7 @@ def generators(self: _Self) -> Iterator[Element]:
 
 _copy_cxx_mem_fns(_RightActionPPerm1PPerm1, Action)
 
-for (
-    _type
-) in (
+for _type in (
     Action._py_template_params_to_cxx_type.values()  # pylint: disable=protected-access
 ):
     _register_cxx_wrapped_type(_type, Action)
@@ -295,14 +289,14 @@ class RightAction(Action):
     """
     Class representing a right action of a semigroup or monoid on a set.
 
-    This page contains the documentation for the class ``RightAction``, which
-    just calls :any:`Action` with the keyword arguments *func* given by
+    This page contains the documentation for the class :any:`RightAction`,
+    which just calls :any:`Action` with the keyword arguments *func* given by
     :any:`ImageRightAction` and *side* given by :py:class:`side.right`.
     """
 
     def __init__(self: _Self, *args, generators=None, seeds=None) -> None:
         """
-        :sig=(self: Action, generators=None, seeds=None, func=None, side=None) -> None:
+        :sig=(self: RightAction, generators=None, seeds=None) -> None:
 
         Construct an :any:`Action` from generators and seeds,
         :any:`ImageRightAction` and :py:class:`side.right`.
@@ -318,6 +312,10 @@ def __init__(self: _Self, *args, generators=None, seeds=None) -> None:
             if *generators* or *seeds* has length ``0``.
         :raises KeyError:
             if the action given by the arguments is not yet implemented.
+
+        .. |name| replace:: :any:`RightAction`
+
+        .. include:: ../../_static/runner_non_inherit.rst
         """
         super().__init__(
             *args,
@@ -344,7 +342,7 @@ class LeftAction(Action):
 
     def __init__(self: _Self, *args, generators=None, seeds=None) -> None:
         """
-        :sig=(self: Action, generators=None, seeds=None, func=None, side=None) -> None:
+        :sig=(self: LeftAction, generators=None, seeds=None) -> None:
 
         Construct an :any:`Action` from generators and seeds,
         :any:`ImageLeftAction` and :py:class:`side.left`.
@@ -360,6 +358,10 @@ def __init__(self: _Self, *args, generators=None, seeds=None) -> None:
             if *generators* or *seeds* has length ``0``.
         :raises KeyError:
             if the action given by the arguments is not yet implemented.
+
+        .. |name| replace:: :any:`LeftAction`
+
+        .. include:: ../../_static/runner_non_inherit.rst
         """
         super().__init__(
             generators=generators,

src/runner.cpp

@@ -56,13 +56,26 @@ The time between the given point and now.
                                R"pbdoc(
 Collection of values related to reporting.
 
-This class exists to collect some values related to reporting in its derived
-classes. These values are:
+This class exists to collect some values related to reporting in its
+derived [#sortof]_ classes. These values are:
 
 -  :any:`report_prefix()`;
 -  :any:`report_every()`;
 -  :any:`last_report()`;
 -  :any:`start_time()`.
+
+This class has limited (no?) utility on its own, and you are unlikely to want to use it directly.
+
+.. important::
+
+   The classes that we claim derive from :any:`Reporter` in this documentation have all the methods of the
+   :any:`Reporter` class but, for boring technical reasons, are not formally
+   subclasses of :any:`Reporter`. If ``thing`` is an instance of a class
+   derived from :any:`Reporter`, then you can use ``thing`` as if it were an
+   instance of :any:`Reporter` but ``isinstance(thing, Reporter)`` will return
+   ``False``.
+
+.. [#sortof] Sort of, please see the note above.
 )pbdoc");
 
     thing.def(py::init<>(), R"pbdoc(
@@ -239,13 +252,13 @@ run at the outmost level.
     py::class_<Runner, Reporter> thing(m,
                                        "Runner",
                                        R"pbdoc(
-Abstract class for derived classes that run an algorithm.
+Abstract class for derived [#sortof]_ classes that run an algorithm.
 
-Many of the classes in ``libsemigroups`` implementing the algorithms, that are
-the reason for the existence of this library, are derived from :any:`Runner`.
-The :any:`Runner` class exists to collect various common tasks required by such
-a derived class with a possibly long running :any:`run`. These common tasks
-include:
+Many of the classes in ``libsemigroups_pybind11`` implementing the algorithms,
+that are the reason for the existence of this package, are derived from
+:any:`Runner`. The :any:`Runner` class exists to collect various common tasks
+required by such a derived class with a possibly long running :any:`run`. These
+common tasks include:
 
 *  running for a given amount of time (:any:`run_for`)
 *  running until a nullary predicate is true (:any:`run_until`)
@@ -254,7 +267,19 @@ a derived class with a possibly long running :any:`run`. These common tasks
    out (:any:`timed_out`)? has it :any:`stopped` for any reason?
 *  permit the function :any:`run` to be killed from another thread (:any:`kill`).
 
+Because :any:`Runner` is an abstract class it is not possible to create instances of :any:`Runner` except via a derived class.
+
 This class inherits from :any:`Reporter`.
+
+.. important::
+
+   The classes derived from :any:`Runner` have all the methods of the
+   :any:`Runner` class but, for boring technical reasons, are not formally
+   subclasses of :any:`Runner`. If ``thing`` is an instance of a class derived
+   from :any:`Runner`, then you can use ``thing`` as if it were an instance of
+   :any:`Runner` but ``isinstance(thing, Runner)`` will return ``False``.
+
+.. [#sortof] Sort of, please see the note above.
 )pbdoc");
 
     py::enum_<Runner::state> state(m, "Runner.state", R"pbdoc(

src/schreier-sims.cpp

@@ -106,7 +106,7 @@ Add a base point to the stabiliser chain.
 
 :raises LibsemigroupsError:  if *pt* is already a base point.
 
-:raises LibsemigroupsError:  if :any:`Runner.finished()` returns ``True``.
+:raises LibsemigroupsError:  if :any:`finished()` returns ``True``.
 
 :complexity: Linear in the current number of base points.)pbdoc");
       thing.def("add_generator",