Dot updates

docs/source/data-structures/visualisation/dot.attr.rst

@@ -0,0 +1,14 @@
+..
+    Copyright (c) 2024 J. D. Mitchell
+
+    Distributed under the terms of the GPL license version 3.
+
+    The full license is in the file LICENSE, distributed with this software.
+
+The Dot.Attr enum
+=================
+
+.. autoclass:: libsemigroups_pybind11.Dot.Attr
+    :class-doc-from: class
+    :members:
+    :exclude-members: name

docs/source/data-structures/visualisation/dot.kind.rst

@@ -5,8 +5,8 @@
 
     The full license is in the file LICENSE, distributed with this software.
 
-The Dot.Kind class
-==================
+The Dot.Kind enum
+=================
 
 .. autoclass:: libsemigroups_pybind11.Dot.Kind
     :class-doc-from: class

docs/source/data-structures/visualisation/dot.rst

@@ -43,4 +43,4 @@ Full API
 .. autoclass:: Dot
     :class-doc-from: init
     :members:
-    :exclude-members: Kind, Node, Edge
+    :exclude-members: Kind, Node, Edge, Attr

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

@@ -19,6 +19,7 @@ descriptions in the DOT_ language of Graphviz_ graph drawing software.
     :maxdepth: 1
 
     dot
+    dot.attr
     dot.edge
     dot.kind
     dot.node

docs/source/main-algorithms/froidure-pin/helpers.rst

@@ -16,6 +16,10 @@ Contents
     current_normal_forms
     current_position
     current_rules
+    dot_current_left_cayley_graph
+    dot_current_right_cayley_graph
+    dot_left_cayley_graph
+    dot_right_cayley_graph
     equal_to
     factorisation
     minimal_factorisation

src/bipart.cpp

@@ -588,6 +588,8 @@ partition* of a bipartition *f* is the partition of a subset :math:`P` of
         [](Bipartition& x) { return bipartition::uniform_random(x); },
         py::arg("x"),
         R"pbdoc(
+:sig=(x: Bipartition) -> None:
+
 Replace the contents of a bipartition with a random bipartition.
 
 This function replaces the contents of the bipartition *x* with a random
@@ -632,6 +634,8 @@ at random from among all bipartitions of degree equal to *deg*.
         [](Bipartition& x) { return bipartition::random(x); },
         py::arg("x"),
         R"pbdoc(
+:sig=(x: Bipartition) -> None:
+
 Replace the contents of a bipartition with a random bipartition.
 
 This function replaces the contents of the bipartition *x* with a random

src/dot.cpp

@@ -49,6 +49,67 @@ its DOT_ source code string (:any:`Dot.to_string`). Write the source code to a
 file and render it with the Graphviz_ installation on your system.
 )pbdoc");
 
+    ////////////////////////////////////////////////////////////////////////////
+    // Attr enum
+    ////////////////////////////////////////////////////////////////////////////
+
+    py::options options;
+    options.disable_enum_members_docstring();
+
+    py::enum_<Dot::Attr> attr(dot, "Attr", R"pbdoc(
+The values in this enum can be used to indicate how attribute values are
+written in the DOT_ output.
+
+The valid values are:
+
+.. py:attribute:: Attr.string
+  :value: <Attr.string: 0>
+
+  Value indicating that the attribute value should be written as a quoted
+  string.
+
+.. py:attribute:: Attr.html
+  :value: <Attr.html: 1>
+
+  Value indicating that the attribute value should be written as an HTML-like
+  label.
+)pbdoc");
+    attr.value("string", Dot::Attr::string).value("html", Dot::Attr::html);
+    attr.def("__repr__", [](Dot::Attr const& val) {
+      return to_human_readable_repr(val, ".");
+    });
+
+    ////////////////////////////////////////////////////////////////////////////
+    // Kind enum
+    ////////////////////////////////////////////////////////////////////////////
+
+    py::enum_<Dot::Kind> kind(dot, "Kind", R"pbdoc(
+The values in this enum can be used to indicate the type of a graph.
+
+The valid values are:
+
+.. py:attribute:: Kind.digraph
+  :value: <Kind.digraph: 0>
+
+  Value indicating that the represented graph has directed edges ->.
+
+.. py:attribute:: Kind.graph
+  :value: <Kind.graph: 1>
+
+  Value indicating that the represented graph has undirected edges --.
+
+.. py:attribute:: Kind.subgraph
+  :value: <Kind.subgraph: 2>
+
+  Value indicating that the represented graph is a subgraph of another Dot object.
+)pbdoc");
+    kind.value("digraph", Dot::Kind::digraph)
+        .value("graph", Dot::Kind::graph)
+        .value("subgraph", Dot::Kind::subgraph);
+    kind.def("__repr__", [](Dot::Kind const& knd) {
+      return to_human_readable_repr(knd, ".");
+    });
+
     ////////////////////////////////////////////////////////////////////////////
     // Node nested class
     ////////////////////////////////////////////////////////////////////////////
@@ -74,7 +135,11 @@ The name of the node.
           &Dot::Node::add_attr<std::string const&, std::string const&>,
           py::arg("key"),
           py::arg("val"),
-          R"pbdoc(Add an attribute to a node.
+          py::arg("kind") = Dot::Attr::string,
+          R"pbdoc(
+:sig=(self: Dot.Node, key: str, val: str, kind: Dot.Attr = Dot.Attr.string) -> Dot.Node:
+
+Add an attribute to a node.
 
 This function adds a new attribute, or replaces the value of an existing
 attribute of a :any:`Dot.Node`.
@@ -83,6 +148,8 @@ attribute of a :any:`Dot.Node`.
 :type key: str
 :param val: the value of the attribute.
 :type val: str
+:param kind: whether to add quotes to *val* or not.
+:type kind: Dot.Attr
 
 :returns: *self*
 :rtype: Dot.Node
@@ -121,7 +188,11 @@ The name (read-only `str`) of the tail of the edge.
           &Dot::Edge::add_attr<std::string const&, std::string const&>,
           py::arg("key"),
           py::arg("val"),
-          R"pbdoc(Add an attribute to an edge.
+          py::arg("kind") = Dot::Attr::string,
+          R"pbdoc(
+:sig=(self: Dot.Edge, key: str, val: str, kind: Dot.Attr = Dot.Attr.string) -> Dot.Edge:
+
+Add an attribute to an edge.
 
 This function adds a new attribute, or replaces the value of an existing
 attribute of an :any:`Edge`.
@@ -130,43 +201,13 @@ attribute of an :any:`Edge`.
 :type key: str
 :param val: the value of the attribute.
 :type val: str
+:param kind: whether to add quotes to *val* or not.
+:type kind: Dot.Attr
 
 :returns: *self*
 :rtype: Dot.Edge
 )pbdoc");
 
-    ////////////////////////////////////////////////////////////////////////////
-    // Kind enum
-    ////////////////////////////////////////////////////////////////////////////
-    py::options options;
-    options.disable_enum_members_docstring();
-    py::enum_<Dot::Kind> kind(dot, "Kind", R"pbdoc(
-The values in this enum can be used to indicate the type of a graph.
-
-The valid values are:
-
-.. py:attribute:: Kind.digraph
-  :value: <Kind.digraph: 0>
-
-  Value indicating that the represented graph has directed edges ->.
-
-.. py:attribute:: Kind.graph
-  :value: <Kind.graph: 1>
-
-  Value indicating that the represented graph has undirected edges --.
-
-.. py:attribute:: Kind.subgraph
-  :value: <Kind.subgraph: 2>
-
-  Value indicating that the represented graph is a subgraph of another Dot object.
-)pbdoc");
-    kind.value("digraph", Dot::Kind::digraph)
-        .value("graph", Dot::Kind::graph)
-        .value("subgraph", Dot::Kind::subgraph);
-    kind.def("__repr__", [](Dot::Kind const& knd) {
-      return to_human_readable_repr(knd, ".");
-    });
-
     ////////////////////////////////////////////////////////////////////////////
     // Dot members
     ////////////////////////////////////////////////////////////////////////////
@@ -474,7 +515,11 @@ representation of the graph in the DOT_ language for Graphviz_.
             &Dot::add_attr<std::string const&, std::string const&>,
             py::arg("key"),
             py::arg("val"),
-            R"pbdoc(Add an attribute to a :any:`Dot` object.
+            py::arg("kind") = Dot::Attr::string,
+            R"pbdoc(
+:sig=(self: Dot, key: str, val: str, kind: Dot.Attr = Dot.Attr.string) -> Dot:
+
+Add an attribute to a :any:`Dot` object.
 
 This function adds a new attribute, or replaces the value of an existing
 attribute of an :any:`Dot`.
@@ -483,6 +528,8 @@ attribute of an :any:`Dot`.
 :type key: str
 :param val: the value of the attribute.
 :type val: str
+:param kind: whether to add quotes to *val* or not.
+:type kind: Dot.Attr
 
 :returns: *self*
 :rtype: Dot
@@ -492,7 +539,10 @@ attribute of an :any:`Dot`.
     dot.def("add_attr",
             &Dot::add_attr<std::string const&>,
             py::arg("key"),
-            R"pbdoc(Add an attribute to a :any:`Dot` object.
+            R"pbdoc(
+:sig=(self: Dot, key: str) -> Dot:
+
+Add an attribute to a :any:`Dot` object.
 
 This function adds a new attribute, or replaces the value of an existing
 attribute of an :any:`Dot`.