Doc: Fix nitpicky warnings

Author: Joseph-Edwards

docs/source/_ext/libsemigroups_pybind11_extensions.py

@@ -440,6 +440,7 @@ def check_string_replacements(app, env):
         logger.info(f"Please correct this in {__file__}")
 
 
+# TODO: Check this actually works as expected.
 def document_class(app, what, name, obj, options, lines):
     """Document a class using its __init__ function
 
@@ -450,7 +451,18 @@ def document_class(app, what, name, obj, options, lines):
     if what != "class":
         return
     try:
-        if options["class-doc-from"] == "init":
+        if options["class-doc-from"] != "init":
+            return
+
+        init_doc = obj.__init__.__doc__
+
+        if (
+            not init_doc
+            or "Initialize self.  See help(type(self)) for accurate signature."
+            in init_doc
+        ):
+            lines[:] = []
+        else:
             lines[:] = [f".. autofunction:: {name}.__init__\n"]
     except KeyError:
         return

docs/source/main-algorithms/core-classes/runner.rst

@@ -42,7 +42,6 @@ Full API
 --------
 
 .. autoclass:: Runner
-    :no-doc:
     :class-doc-from: init
     :members:
     :exclude-members: state

docs/source/main-algorithms/knuth-bendix/helpers.rst

@@ -14,7 +14,7 @@ submodule ``libsemigroups_pybind11.knuth_bendix``.
 
 .. seealso::
 
-    :py:class:`overlap`
+    :any:`KnuthBendix.options`
 
 Contents
 --------

docs/source/main-algorithms/schreier-sims/class.rst

@@ -51,8 +51,8 @@ Full API
     :class-doc-from: init
     :members:
     :exclude-members: 
-        current_state, dead, finished, internal_generating_pairs,
+        current_state, dead, internal_generating_pairs,
         kill, last_report, report, report_every, report_prefix,
-        report_why_we_stopped, reset_last_report, reset_start_time, run, run_for,
+        report_why_we_stopped, reset_last_report, reset_start_time, run_for,
         run_until, running, running_for, running_until, start_time, started, state,
         stopped, stopped_by_predicate, success, timed_out

src/action.cpp

@@ -523,18 +523,30 @@ This function returns the point obtained by applying the action defined by
   }  // namespace
 
   void init_action(py::module& m) {
-    py::enum_<side>(
-        m,
-        "side",
-        R"pbdoc(This value indicates that the action in an :any:`Action` instance should be a left action.)pbdoc")
-        .value(
-            "left",
-            side::left,
-            R"pbdoc(This value indicates that the action in an :any:`Action` instance should be a left action.)pbdoc")
-        .value(
-            "right",
-            side::right,
-            R"pbdoc(This value indicates that the action in an :any:`Action` instance should be a right action.)pbdoc");
+    py::options options;
+    options.disable_enum_members_docstring();
+    py::enum_<side>(m,
+                    "side",
+                    R"pbdoc(
+The values in this enum can be used to indicate that the action in an
+:any:`Action` instance should be a left action.
+
+The valid values are:
+
+.. py:attribute:: side.left
+  :value: <side.left: 0>
+
+   Value indicating that the action in an :any:`Action` instance should be a
+   left action.
+
+.. py:attribute:: side.right
+  :value: <side.left: 1>
+
+   Value indicating that the action in an :any:`Action` instance should be a
+   right action.
+)pbdoc")
+        .value("left", side::left)
+        .value("right", side::right);
 
     // One call to bind is required per list of types
 

src/bmat8.cpp

@@ -49,11 +49,6 @@ be ``0``. This does not affect the results of any calculations.
 There are numerous functions for computing things about :any:`BMat8` objects in
 the submodule ``bmat8``.
 
-.. toctree::
-   :maxdepth: 1
-
-   bmat8-helpers
-
 .. doctest::
 
    >>> from libsemigroups_pybind11 import BMat8

src/forest.cpp

@@ -162,7 +162,7 @@ Returns the label of the edge from a node to its parent.
 :param i:
    the node whose label is sought.
 :type i:
-  init
+  int
 
 :returns:
    The label of the edge from the parent of *i* to *i*.

src/froidure-pin-base.cpp

@@ -762,7 +762,7 @@ use :any:`current_rules` instead.
 :returns:
     An iterator yielding rules.
 :rtype:
-    Iterator[tuple[list[int],list[int]]]:
+    Iterator[tuple[list[int],list[int]]]
 )pbdoc");
     }
   }  // init_froidure_pin_base

src/froidure-pin.cpp

@@ -346,16 +346,66 @@ element of *fp* and ``False`` otherwise.
             return froidure_pin::factorisation(fpb, pos);
           },
           py::arg("fpb"),
-          py::arg("pos"));
+          py::arg("pos"),
+          R"pbdoc(
+:sig=(fp: FroidurePin, x: Element | int) -> list[int]:
+:only-document-once:
+
+Returns a word containing a factorisation (in the generators) of an
+element.
+
+This function returns a word in the generators that equals the given element
+*x*. The key difference between this function and :any:`minimal_factorisation`,
+is that the resulting factorisation may not be minimal.
+
+:param fp: the :any:`FroidurePin` instance.
+:type fp: FroidurePin
+
+:param x: a possible element, or index of element, to factorise.
+:type x: Element | int
+
+:returns: Returns a word in the generators which evaluates to *x*.
+:rtype: list[int]
+
+:raises LibsemigroupsError:
+  if *x* is an ``Element`` and *x* does not belong to *fp*.
+
+:raises LibsemigroupsError:
+  if *x* is an :any:`int` and *x* is greater than or equal to :any:`FroidurePin.size`.
+
+)pbdoc");
 
-      // Documented in the Element overload.
       m.def(
           "froidure_pin_minimal_factorisation",
           [](FroidurePin_& fp, size_t i) {
             return froidure_pin::minimal_factorisation(fp, i);
           },
           py::arg("fp"),
-          py::arg("i"));
+          py::arg("i"),
+          R"pbdoc(
+:sig=(fp: FroidurePin, x: Element | int) -> list[int]:
+:only-document-once:
+Returns a word containing a minimal factorisation (in the generators)
+of an element.
+
+This function returns the short-lex minimum word (if any) in the generators
+that evaluates to *x*.
+
+:param fp: the :any:`FroidurePin` instance.
+:type fp: FroidurePin
+
+:param x: a possible element, or index of element, to factorise.
+:type x: Element | int
+
+:returns: A word in the generators that evaluates to *x*.
+:rtype: list[int]
+
+:raises LibsemigroupsError:
+  if *x* is an ``Element`` and *x* does not belong to *fp*.
+
+:raises LibsemigroupsError:
+  if *x* is an :any:`int` and *x* is greater than or equal to :any:`FroidurePin.size`.
+)pbdoc");
 
       m.def(
           "froidure_pin_position",
@@ -875,6 +925,7 @@ if *x* is not an element.
       // Helper functions
       ////////////////////////////////////////////////////////////////////////
 
+      // Documented in the size_t overload.
       m.def(
           "froidure_pin_factorisation",
           [](FroidurePin_& fp, Element const& x) {
@@ -884,29 +935,6 @@ if *x* is not an element.
           py::arg("x"),
           R"pbdoc(
 :sig=(fp: FroidurePin, x: Element | int) -> list[int]:
-:only-document-once:
-
-Returns a word containing a factorisation (in the generators) of an
-element.
-
-This function returns a word in the generators that equals the given element
-*x*. The key difference between this function and :any:`minimal_factorisation`,
-is that the resulting factorisation may not be minimal.
-
-:param fp: the :any:`FroidurePin` instance.
-:type fp: FroidurePin
-
-:param x: a possible element, or index of element, to factorise.
-:type x: Element | int
-
-:returns: Returns a word in the generators which evaluates to *x*.
-:rtype: list[int]
-
-:raises LibsemigroupsError:
-  if *x* is an ``Element`` and *x* does not belong to *fp*.
-
-:raises LibsemigroupsError:
-  if *x* is an :any:`int` and *x* is greater than or equal to :any:`FroidurePin.size`.
 )pbdoc");
 
       m.def(
@@ -918,28 +946,6 @@ is that the resulting factorisation may not be minimal.
           py::arg("x"),
           R"pbdoc(
 :sig=(fp: FroidurePin, x: Element | int) -> list[int]:
-:only-document-once:
-
-Returns a word containing a minimal factorisation (in the generators)
-of an element.
-
-This function returns the short-lex minimum word (if any) in the generators
-that evaluates to *x*.
-
-:param fp: the :any:`FroidurePin` instance.
-:type fp: FroidurePin
-
-:param x: a possible element, or index of element, to factorise.
-:type x: Element | int
-
-:returns: A word in the generators that evaluates to *x*.
-:rtype: list[int]
-
-:raises LibsemigroupsError:
-  if *x* is an ``Element`` and *x* does not belong to *fp*.
-
-:raises LibsemigroupsError:
-  if *x* is an :any:`int` and *x* is greater than or equal to :any:`FroidurePin.size`.
 )pbdoc");
 
       m.def(
@@ -1219,34 +1225,49 @@ This function returns the element of *fp* obtained by evaluating *w*.
         // Helpers
         ////////////////////////////////////////////////////////////////////////
 
-        m.def("froidure_pin_factorisation",
-              [](FroidurePin_& fp, ElementStateful<FroidurePin_> const& x) {
-                return froidure_pin::factorisation(fp, to_element(x));
-              });
+        m.def(
+            "froidure_pin_factorisation",
+            [](FroidurePin_& fp, ElementStateful<FroidurePin_> const& x) {
+              return froidure_pin::factorisation(fp, to_element(x));
+            },
+            R"pbdoc(
+:sig=(fp: FroidurePin, x: Element | int) -> list[int]:
+)pbdoc");
 
-        m.def("froidure_pin_factorisation",
-              [](FroidurePin_& fp, Word const& x) {
-                return froidure_pin::factorisation(fp, to_element(fp, x));
-              });
+        m.def(
+            "froidure_pin_factorisation",
+            [](FroidurePin_& fp, Word const& x) {
+              return froidure_pin::factorisation(fp, to_element(fp, x));
+            },
+            R"pbdoc(
+:sig=(fp: FroidurePin, x: Element | int) -> list[int]:
+)pbdoc");
 
-        m.def("froidure_pin_minimal_factorisation",
-              [](FroidurePin_& fp, ElementStateful<FroidurePin_> const& x) {
-                return froidure_pin::minimal_factorisation(fp, to_element(x));
-              });
+        m.def(
+            "froidure_pin_minimal_factorisation",
+            [](FroidurePin_& fp, ElementStateful<FroidurePin_> const& x) {
+              return froidure_pin::minimal_factorisation(fp, to_element(x));
+            },
+            R"pbdoc(
+:sig=(fp: FroidurePin, x: Element | int) -> list[int]:
+)pbdoc");
 
-        m.def("froidure_pin_minimal_factorisation",
-              [](FroidurePin_& fp, Word const& x) {
-                return froidure_pin::minimal_factorisation(fp,
-                                                           to_element(fp, x));
-              });
+        m.def(
+            "froidure_pin_minimal_factorisation",
+            [](FroidurePin_& fp, Word const& x) {
+              return froidure_pin::minimal_factorisation(fp, to_element(fp, x));
+            },
+            R"pbdoc(
+:sig=(fp: FroidurePin, x: Element | int) -> list[int]:
+)pbdoc");
 
         m.def("froidure_pin_to_element",
               [](FroidurePin_& fp, word_type const& w) {
                 return from_element(fp, froidure_pin::to_element(fp, w));
               });
       }
     }  // bind_froidure_pin_stateful
-  }  // namespace
+  }    // namespace
 
   void init_froidure_pin(py::module& m) {
     // TODO(0) uncomment bind_froidure_pin<HPCombiTransf<16>>(m, "Transf16");

src/knuth-bendix-impl.cpp

@@ -64,9 +64,11 @@ namespace libsemigroups {
       py::class_<typename KnuthBendixImpl<Rewriter>::options> options(thing,
                                                                       "options",
                                                                       R"pbdoc(
-This class containing various options that can be used to control the
+This class contains various options that can be used to control the
 behaviour of Knuth-Bendix.)pbdoc");
 
+      py::options enum_options;
+      enum_options.disable_enum_members_docstring();
       py::enum_<typename KnuthBendixImpl<Rewriter>::options::overlap>(options,
                                                                       "overlap",
                                                                       R"pbdoc(
@@ -78,17 +80,29 @@ The values in this enum determine how a :any:`KnuthBendix`
 instance measures the length :math:`d(AB, BC)` of the overlap of
 two words :math:`AB` and :math:`BC`.
 
+The valid values are:
+
+.. py:attribute:: overlap.ABC
+  :value: <overlap.ABC: 0>
+
+  :math:`d(AB, BC) = |A| + |B| + |C|`
+
+.. py:attribute:: overlap.AB_BC
+  :value: <overlap.AB_BC: 1>
+
+  :math:`d(AB, BC) = |AB| + |BC|`
+
+.. py:attribute:: overlap.MAX_AB_BC
+  :value: <overlap.MAX_AB_BC: 2>
+
+  :math:`d(AB, BC) = max(|AB|, |BC|)`
+
 .. seealso:: :any:`KnuthBendix.overlap_policy`
 )pbdoc")
-          .value("ABC",
-                 KnuthBendixImpl<Rewriter>::options::overlap::ABC,
-                 R"pbdoc(:math:`d(AB, BC) = |A| + |B| + |C|`)pbdoc")
-          .value("AB_BC",
-                 KnuthBendixImpl<Rewriter>::options::overlap::AB_BC,
-                 R"pbdoc(:math:`d(AB, BC) = |AB| + |BC|`)pbdoc")
+          .value("ABC", KnuthBendixImpl<Rewriter>::options::overlap::ABC)
+          .value("AB_BC", KnuthBendixImpl<Rewriter>::options::overlap::AB_BC)
           .value("MAX_AB_BC",
-                 KnuthBendixImpl<Rewriter>::options::overlap::MAX_AB_BC,
-                 R"pbdoc(:math:`d(AB, BC) = max(|AB|, |BC|)`)pbdoc");
+                 KnuthBendixImpl<Rewriter>::options::overlap::MAX_AB_BC);
 
       thing.def("__repr__", [](KnuthBendixImpl<Rewriter>& self) {
         return to_human_readable_repr(self);