polished docs a little

Author: jjcmoon

src/circuit.cpp

@@ -479,7 +479,7 @@ nb::class_<NodePtr>(m, "NodePtr")
 
 nb::class_<Circuit>(m, "Circuit", "Circuits are the main class added by KLay, and require no arguments to construct.\n\n:code:`circuit = klay.Circuit()` ")
 .def(nb::init<>())
-.def("add_sdd_from_file", &Circuit::add_sdd_from_file, "filename"_a, "true_lits"_a = std::vector<int>(), "false_lits"_a = std::vector<int>(), "Add an SDD circuit from file.\n\n:param filename:\n\tPath to the :code:`.sdd` file on disk.\n:param true_lits:\n\tList of literals that are always true and should get propagated away.\n:param false_lits:\n\tList of literals that are always false and should get propagated away.")
+.def("add_sdd_from_file", &Circuit::add_sdd_from_file, "filename"_a, "true_lits"_a = std::vector<int>(), "false_lits"_a = std::vector<int>(), "Add a sentential decision diagram (SDD) from file.\n\n:param filename:\n\tPath to the :code:`.sdd` file on disk.\n:param true_lits:\n\tList of literals that are always true and should get propagated away.\n:param false_lits:\n\tList of literals that are always false and should get propagated away.")
 .def("add_d4_from_file", &Circuit::add_d4_from_file, "filename"_a, "true_lits"_a = std::vector<int>(), "false_lits"_a = std::vector<int>(), "Add an NNF circuit in the D4 format from file.\n\n:param filename:\n\tPath to the :code:`.nnf` file on disk.\n:param true_lits:\n\tList of literals that are always true and should get propagated away.\n:param false_lits:\n\tList of literals that are always false and should get propagated away.")
 .def("_get_indices", &Circuit::get_indices)
 .def("nb_nodes", &Circuit::nb_nodes, "Number of nodes in the circuit.")
@@ -489,8 +489,8 @@ nb::class_<Circuit>(m, "Circuit", "Circuits are the main class added by KLay, an
 .def("literal_node", &Circuit::literal_node, "Adds a literal node to the circuit, and returns a pointer to this node.", "literal"_a)
 .def("or_node", &Circuit::or_node, "children"_a, "Adds an :code:`or` node to the circuit, and returns a pointer to this node.")
 .def("and_node", &Circuit::and_node, "children"_a, "Adds an :code:`and` node to the circuit, and returns a pointer to this node.")
-.def("set_root", &Circuit::set_root, "root"_a, "Marks a node pointer as root. The order in which nodes are set as root determines the order of the output tensor. Only use this when manually constructing a circuit, when loading in a NNF/SDD its root is automatically set as root.")
-.def("remove_unused_nodes", &Circuit::remove_unused_nodes, "Removes unused non-root nodes from the circuit.\nWarning: this invalidates any :code:`NodePtr` referring to an unused node (i.e., a node not connected to a root node).");
+.def("set_root", &Circuit::set_root, "root"_a, "Marks a node pointer as root. The order in which nodes are set as root determines the order of the output tensor.\n .. note:: Only use this when manually constructing a circuit, when loading in a NNF/SDD its root is automatically set as root.\n")
+.def("remove_unused_nodes", &Circuit::remove_unused_nodes, "Removes unused nodes from the circuit. Root nodes are always considered used.\n .. warning:: Invalidates any :code:`NodePtr` referring to an unused node (i.e., a node not connected to a root node).\n");
 
 m.def("to_dot_file", &to_dot_file, "circuit"_a, "filename"_a, "Write the given circuit as dot format to a file");
 }

src/klay/__init__.py

@@ -10,9 +10,9 @@ def to_torch_module(self: Circuit, semiring: str = "log", probabilistic: bool =
     Convert the circuit into a PyTorch module.
 
     :param semiring:
-        The semiring in which the circuit should be evaluated. Supported options are ("log", "real", "mpe", "godel").
+        The semiring in which the circuit should be evaluated. Supported options are :code:`"log"`, :code:`"real"`, :code:`"mpe"`, or :code:`"godel"`.
     :param probabilistic:
-        If true, construct a probabilistic circuit instead of an arithmetic circuit.
+        If enabled, construct a probabilistic circuit instead of an arithmetic circuit.
         This means the inputs to a sum node are multiplied by a probability, and
         we can interpret sum nodes as latent Categorical variables.
     """
@@ -26,28 +26,33 @@ def to_jax_function(self: Circuit, semiring: str = "log"):
     Convert the circuit into a Jax function.
 
     :param semiring:
-        The semiring in which the circuit should be evaluated. Supported options are ("log", "real", "mpe", "godel").
+        The semiring in which the circuit should be evaluated. Supported options are :code:`"log"`, :code:`"real"`, :code:`"mpe"`, or :code:`"godel"`.
     """
     from .jax import create_knowledge_layer
     indices = self._get_indices()
     return create_knowledge_layer(*indices, semiring=semiring)
 
 
-def add_sdd(self: Circuit, sdd: "SddNode", true_lits: Sequence[int] = (), false_lits: Sequence[int] = ()):
+def add_sdd(self: Circuit, sdd: "SddNode", true_lits: Sequence[int] = (), false_lits: Sequence[int] = ()) -> NodePtr:
     """
     Add an SDD to the Circuit.
 
+    :param sdd:
+        PySDD `SDDNode`_ to be added.
     :param true_lits:
         List of literals that are always true and should get propagated away.
     :param false_lits:
         List of literals that are always false and should get propagated away.
+
+    .. _SDDNode: https://pysdd.readthedocs.io/en/latest/classes/SddNode.html
     """
     import os
     from pathlib import Path
 
     sdd.save(bytes(Path("tmp.sdd")))
-    self.add_sdd_from_file("tmp.sdd", true_lits, false_lits)
+    root = self.add_sdd_from_file("tmp.sdd", true_lits, false_lits)
     os.remove("tmp.sdd")
+    return root
 
 
 Circuit.to_torch_module = to_torch_module