Skip to content

Doc fixes #420

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
james-d-mitchell merged 9 commits into from
May 1, 2026
Merged

Doc fixes #420

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
32f2ef8
presentation: minor doc fixes
james-d-mitchell Apr 30, 2026
8b8f3b0
Fix presentation documentation issues
codex Apr 30, 2026
3410e0e
Fix action side enum docs
codex Apr 30, 2026
cef1a53
Fix Aho-Corasick documentation issues
codex Apr 30, 2026
8a8f311
Fix bipartition documentation issues
codex Apr 30, 2026
4d7398c
Fix congruence common documentation issues
codex Apr 30, 2026
cf99d85
Fix congruence documentation wording
codex Apr 30, 2026
da849d3
Fix Dot documentation wording
codex Apr 30, 2026
78eb02a
Fix forest documentation wording
codex Apr 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions src/action.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -530,7 +530,7 @@ This function returns the point obtained by applying the action defined by
"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.
:any:`Action` instance should be a left or right action.

The valid values are:

Expand All @@ -541,7 +541,7 @@ The valid values are:
left action.

.. py:attribute:: side.right
:value: <side.left: 1>
:value: <side.right: 1>

Value indicating that the action in an :any:`Action` instance should be a
right action.
Expand Down
34 changes: 19 additions & 15 deletions src/aho-corasick.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,8 +54,7 @@ The implementation of :any:`AhoCorasick` uses two different types of node;
in the trie. An inactive node is a node that used to be part of the trie, but
has since been removed. It may later become active again after being
reinitialised, and exists as a way of minimising how frequently memory needs
to be allocated and deallocated for nodes. This function validates whether the
given index *i* corresponds to an active node.
to be allocated and deallocated for nodes.

Several helper functions are provided in the ``aho_corasick`` module, documented
:doc:`here <helpers>`.
Expand Down Expand Up @@ -110,7 +109,7 @@ This function returns the index of the child of the node with index
:returns: the index of the child.
:rtype: int | Undefined

:raises LibsemigroupsError: if ``throw_if_node_index_not_active(parent)`` throws.
:raises LibsemigroupsError: if ``throw_if_node_index_not_active(parent)`` raises an exception.
Copy link
Copy Markdown
Collaborator

@Joseph-Edwards Joseph-Edwards Apr 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this is a good change, but we should be consistent. There are instances of this in other files that we should probably change too.

Copy link
Copy Markdown
Collaborator

@Joseph-Edwards Joseph-Edwards Apr 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more. 

> rg "if .* throws\."
src/sims.cpp
113::raises LibsemigroupsError: if :any:`Presentation.throw_if_bad_alphabet_or_rules` throws.

src/ukkonen.cpp
64::raises LibsemigroupsError:  if ``throw_if_contains_unique_letter(w)`` throws.
120::raises LibsemigroupsError:  if ``u.throw_if_contains_unique_letter(w)`` throws.
179::raises LibsemigroupsError:  if ``u.throw_if_contains_unique_letter(w)`` throws.
213::raises LibsemigroupsError:  if ``u.throw_if_contains_unique_letter(w)`` throws.
247::raises LibsemigroupsError:  if ``u.throw_if_contains_unique_letter(w)`` throws.
279::raises LibsemigroupsError:  if ``u.throw_if_contains_unique_letter(w)`` throws.
315::raises LibsemigroupsError:  if ``u.throw_if_contains_unique_letter(w)`` throws.
348::raises LibsemigroupsError:  if ``u.throw_if_contains_unique_letter(w)`` throws.
382::raises LibsemigroupsError:  if ``u.throw_if_contains_unique_letter(w)`` throws.
418::raises LibsemigroupsError:  if ``u.throw_if_contains_unique_letter(w)`` throws.
451::raises LibsemigroupsError:  if ``u.throw_if_contains_unique_letter(w)`` throws.
489::raises LibsemigroupsError:  if ``u.throw_if_contains_unique_letter(w)`` throws.
529::raises LibsemigroupsError:  if ``u.throw_if_contains_unique_letter(w)`` throws.

src/present.cpp
1297::raises LibsemigroupsError:  if :any:`throw_if_bad_alphabet_or_rules` throws.
1322::raises LibsemigroupsError:  if :any:`throw_if_bad_alphabet_or_rules` throws.
1363::raises LibsemigroupsError:  if throw_if_bad_alphabet_or_rules throws.
1431::raises LibsemigroupsError:  if ``p.throw_if_bad_alphabet_or_rules()`` throws.
1482:  if :any:`Presentation.throw_if_bad_alphabet_or_rules` throws.
1516:  if :any:`throw_if_bad_alphabet_or_rules` throws.
1586::raises LibsemigroupsError:  if no inverses have been set, or if ``index(x)`` throws.

Copy link
Copy Markdown
Member Author

@james-d-mitchell james-d-mitchell Apr 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed but I think I'll fix this in a separate PR, so you don't have to re-review this one.

Copy link
Copy Markdown
Member Author

@james-d-mitchell james-d-mitchell Apr 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Addressed in #423


:complexity: Constant.

Expand All @@ -130,7 +129,7 @@ Calculate the height of a node.
:returns: the height.
:rtype: int

:raises LibsemigroupsError: if ``throw_if_node_index_not_active(i)`` throws.
:raises LibsemigroupsError: if ``throw_if_node_index_not_active(i)`` raises an exception.

:complexity:
Linear in the return value which is, at worst, the maximum length
Expand Down Expand Up @@ -158,9 +157,9 @@ if it had been newly default constructed.
R"pbdoc(
Returns the number of nodes in the trie.

This function Returns the number of nodes in the trie.
This function returns the number of nodes in the trie.

:returns: The number of nodes>
:returns: The number of nodes.
:rtype: int

:complexity: Constant
Expand Down Expand Up @@ -206,7 +205,7 @@ the longest proper suffix of :math:`W` contained in the trie.
:returns: The index of the suffix link.
:rtype: int

:raises LibsemigroupsError: if ``throw_if_node_index_not_active(current)`` throws.
:raises LibsemigroupsError: if ``throw_if_node_index_not_active(current)`` raises an exception.

:complexity: Linear in the height of the node.

Expand Down Expand Up @@ -240,10 +239,10 @@ trie.
:returns: The index of the node traversed to
:rtype: int

:raises LibsemigroupsError: if ``throw_if_node_index_not_active(current)`` throws.
:raises LibsemigroupsError:
if ``throw_if_node_index_not_active(current)`` raises an exception.

.. seealso:: :any:`throw_if_node_index_not_active`.

)pbdoc");

thing.def("throw_if_node_index_not_active",
Expand All @@ -257,7 +256,8 @@ Check if an index corresponds to a node currently in the trie.
:param i: the index to validate
:type i: int

:raises LibsemigroupsError: if ``throw_if_node_index_out_of_range(i)`` throws, or if *i* is
:raises LibsemigroupsError:
if ``throw_if_node_index_out_of_range(i)`` raises an exception, or if *i* is
not an active node.

:complexity: Constant
Expand Down Expand Up @@ -351,8 +351,7 @@ Add a word to the trie of *ac*
Calling this function immediately adds the word *w* to the trie of *ac*, and
makes the final node on the path labelled by this word terminal (if it
wasn't already). After adding a word, existing suffix links become
invalid. If an identical word has already been added to the trie of *ac*, then
this function does nothing.
invalid.

:param ac: object whose trie is to be added to
:type ac: AhoCorasick
Expand All @@ -364,6 +363,9 @@ this function does nothing.
This node will have a :any:`signature` equal to that of *w*.
:rtype: int

:raises LibsemigroupsError:
if an identical word has already been added to the trie of *ac*.

:complexity: Linear in the length of *w*.

.. seealso:: :any:`AhoCorasick.signature`
Expand Down Expand Up @@ -397,10 +399,9 @@ that correspond to the largest suffix *w*, such that each :math:`n_i` has either
zero children or one. After this, existing suffix links become invalid.

If *w* corresponds to a terminal node :math:`n` with children, then calling this
function makes :math`n` not terminal.
function makes :math:`n` not terminal.

If *w* does not correspond to a terminal node, then calling this function does
nothing.
If *w* does not correspond to a terminal node, then this function raises an exception.

:param ac: the trie.
:type ac: AhoCorasick
Expand All @@ -411,6 +412,9 @@ nothing.
:returns: The index corresponding to the node with signature equal to *w*.
:rtype: int

:raises LibsemigroupsError:
if *w* does not correspond to a terminal node.

:complexity: Linear in the length of *w*.

.. seealso:: :any:`AhoCorasick.signature`
Expand Down
14 changes: 7 additions & 7 deletions src/bipart.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -319,7 +319,7 @@ The parameter *lookup*:
* must have length :math:`2n` for some positive integer :math:`n`;
* consist of non-negative integers; and
* have the property that if :math:`i`, :math:`i > 0` occurs in *lookup*,
then :math:`i - 1` occurs earlier in *lookup*. The value of ``blocks[i]``
then :math:`i - 1` occurs earlier in *lookup*. The value of ``lookup[i]``
should represent the index of the block containing ``i``.

For example, if *lookup* is ``[0, 1, 1, 2, 1, 1, 3, 1, 1, 4, 5, 6]``, then
Expand Down Expand Up @@ -503,13 +503,13 @@ are referred to as the *transverse* blocks.
&Bipartition::one,
py::arg("n"),
R"pbdoc(
:sig=(self: Bipartition, n: int) -> Bipartition:
:sig=(n: int) -> Bipartition:

Return the identity bipartition of given degree.

Returns the identity bipartition of degree ``n``. The *identity bipartition* of
degree :math:`n` has blocks :math:`\{i, -i\}` for all :math:`i\in \{0, \ldots,
n - 1\}`. This member function returns a new identity bipartition of degree
degree :math:`n` has blocks :math:`\{i, -i\}` for all :math:`i\in \{1, \ldots,
n\}`. This member function returns a new identity bipartition of degree
equal to ``n``.

:param n: the degree of the identity to be returned.
Expand Down Expand Up @@ -547,7 +547,7 @@ returned list is ``True`` if the block with index ``i`` is transverse and
Return the identity bipartition with the same degree as the given bipartition.

The *identity bipartition* of degree :math:`n` has blocks :math:`\{i, -i\}` for
all :math:`i\in \{0, \ldots, n - 1\}`. This function returns a new identity
all :math:`i\in \{1, \ldots, n\}`. This function returns a new identity
bipartition of degree equal to the degree of *self*.

:param f: a bipartition
Expand All @@ -569,7 +569,7 @@ partition* of a bipartition *f* is the partition of a subset :math:`P` of

- :math:`\{|y|\mid y\in P\} = \{1, \ldots, n\}` ;
- a block of the partition consists of negative numbers if and only if
the corresponding block of *y* is a transverse block.
the corresponding block of *f* is a transverse block.

:param f: the bipartition
:type f: Bipartition
Expand Down Expand Up @@ -622,7 +622,7 @@ at random from among all bipartitions of degree equal to *deg*.
:rtype: Bipartition

:raises LibsemigroupsError:
if the degree of *deg* is too large. The implementation depends on
if *deg* is too large. The implementation depends on
computing several values that can easily exceed the maximum value of any
fixed precision integer or float type. When this occurs this exception is
thrown.)pbdoc");
Expand Down
12 changes: 6 additions & 6 deletions src/cong-common.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -862,7 +862,7 @@ input word.
&Thing::generating_pairs,
make_doc(
R"pbdoc(
:sig=(self : {name}) -> list[list[int] | str]:
:sig=(self: {name}) -> list[list[int] | str]:
{only_document_once}

Get the generating pairs of the congruence.
Expand Down Expand Up @@ -989,7 +989,7 @@ presentation, then this presentation is returned by this function.
py::arg(extra_doc.var.data()),
py::arg("words"),
make_doc(R"pbdoc(
:sig=({var}: {name}, words: list[list[int] | str]) -> list[list[list[int]] | list[str]]:
:sig=({var}: {name}, words: list[list[int] | str]) -> list[list[list[int]]] | list[list[str]]:
{only_document_once}

Partition a list of words.
Expand All @@ -1007,7 +1007,7 @@ triggers a full enumeration of *{var}*.
:type words: list[list[int] | str]

:returns: The partitioned list of words.
:rtype: list[list[list[int]] | list[str]]
:rtype: list[list[list[int]]] | list[list[str]]

{raises}
)pbdoc",
Expand Down Expand Up @@ -1057,7 +1057,7 @@ triggers a full enumeration of *{var}*.
py::arg("words"),
make_doc(
R"pbdoc(
:sig=({var}: {name}, words: list[list[int] | str]) -> list[list[list[int]] | list[str]]:
:sig=({var}: {name}, words: list[list[int] | str]) -> list[list[list[int]]] | list[list[str]]:
{only_document_once}

Find the non-trivial classes in the partition of a list of words.
Expand All @@ -1074,8 +1074,8 @@ instance *{var}*.
:param words: the input list of words.
:type words: list[list[int] | str]

:returns: The partition of the input list.
:rtype: list[list[list[int]] | list[str]]
:returns: The non-trivial classes in the partition of the input list.
:rtype: list[list[list[int]]] | list[list[str]]

{raises})pbdoc",
class_name,
Expand Down
2 changes: 1 addition & 1 deletion src/cong.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -227,7 +227,7 @@ contained in a :any:`Congruence` object.
R"pbdoc(
:sig=(c: Congruence) -> bool:

Function for checking if a congruence obviously has infinite many
Function for checking if a congruence obviously has infinitely many
classes.

This function returns ``True`` if the quotient of the finitely presented
Expand Down
8 changes: 4 additions & 4 deletions src/dot.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,7 @@ 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 an node.
R"pbdoc(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`.
Expand All @@ -95,7 +95,7 @@ attribute of a :any:`Dot.Node`.
py::class_<Dot::Edge> e(dot,
"Edge",
R"pbdoc(
Instances of this nested class represents an edge in the represented graph.
Instances of this nested class represent an edge in the represented graph.

:any:`Edge` objects can only be constructed by calling :any:`Dot.add_edge`.
)pbdoc");
Expand All @@ -105,7 +105,7 @@ Instances of this nested class represents an edge in the represented graph.
"attrs",
[](Dot::Edge& self) { return self.attrs; },
R"pbdoc(
Read-only dictionary containing containing the attributes of the :any:`Edge`.
Read-only dictionary containing the attributes of the :any:`Edge`.
)pbdoc");
e.def_readonly("head",
&Dot::Edge::head,
Expand Down Expand Up @@ -252,7 +252,7 @@ This function adds an edge from the node named *head* to the node named *tail*.
// last edge reference is collected.
py::arg("subgraph"),
R"pbdoc(
This functions adds the :any:`Dot` object *subgraph* as a subgraph of *self*.
This function adds the :any:`Dot` object *subgraph* as a subgraph of *self*.
The following transformations are performed

* the ``label`` attribute of the added subgraph is the :any:`Dot.name` of
Expand Down
Loading