Standardise docstrings + make a note in contributing.md (#203)

* Establish docstring convention

* do file

* algorithms module

* causal_problem class

* graph.node docstrings

* graph module

* MLP submodule docstrings

* Quadrature submodule

* solvers submodule

* Combine tests with contributing docs

* Fix redirect link

* I can't write Python

* Move loose test into subfolder

* Remove reference to ricardo in tests, use CTS treatment again

Author: willGraham01

README.md

@@ -126,7 +126,7 @@ pytest tests
 
 again from the root of the repository.
 
-For more information about the testing suite, please see [the documentation page](./docs/developers/tests.md).
+For more information about the testing suite, please see [the contributing page](./docs/developers/contributing.md#testing-suite).
 
 ### Building documentation
 

docs/developers/tests.md docs/developers/contributing.mddocs/developers/tests.md renamed to docs/developers/contributing.md

@@ -1,9 +1,62 @@
-# Testing Suite
+# Contributing and Style Guide
+
+## Docstring Style
+
+### Functions and Methods
+
+`causalprog` uses [Google-style docstrings](https://mkdocstrings.github.io/python/usage/docstrings/google/), which should be formatted as
+
+```python
+def my_function(arg1, arg2):
+  """
+  Summary line.
+
+  Further information in prose / paragraph format, mathematical notation is also supported here.
+  If some of the function arguments require detailed explanation, this explanation should be placed here.
+
+  Args:
+    arg1: Description of the first argument
+    arg2: Description of the second argument.
+
+  Returns:
+    Description of the object(s) that are returned by the method.
+
+  Raises:
+    ExceptionType: Conditions under which this is raised.
+    ExceptionType: Conditions under which this is raised.
+
+  """
+```
+
+`mkdocs` also supports the `Tip:` and `Note:` syntax within docstrings too, which should appear within the further information section of the docstring.
+
+If a function's purpose, return type, and inputs are clear from it's definition and name, then the docstring may consist of a single summary line instead:
+
+```python
+def sum_items(item1, item2):
+  """Return the sum of two items."""
+  return item1 + item2
+```
+
+### Classes and Modules
+
+Classes and modules should also obey Google-style docstring conventions where possible, but there is no need to provide an explicit listing of the methods (and / or attributes) that such objects provide in the docstrings themselves.
+However, docstrings for classes and modules should still provide an adequate level of detail about what the module does / class represents, and the components that a user will typically be interacting with.
+
+### Docstrings in the Tests and Examples
+
+Outside the package source code, the docstring format is much more loose, though developers should try to stick to the Google-style when possible.
+
+In the test suite; docstrings are typically used to describe the steps in longer, more involved tests, as well as the actual comparisons or `assert`ions that are made to ensure object being tested is functioning correctly.
+
+In the examples; docstrings are typically provided in the summary format, relying on the surrounding prose to provide context for the reader.
+
+## Testing Suite
 
 `causalprog`'s test suite is written using [`pytest`](https://docs.pytest.org/en/stable/).
 The package can be installed with its developer dependencies, including `pytest`, by specifying the `[dev]` optional dependency when installing the package.
 
-## Running the tests
+### Running the tests
 
 To run the test suite, you will need to clone the `causalprog` repository and then install `causalprog` into your developer environment with the `[dev]` optional dependencies.
 We recommend specifying an editable installation if you intend to make contributions to the package.
@@ -29,7 +82,7 @@ Running
 
 in the repository root will do so.
 
-## Organisation of the test suite
+### Organisation of the test suite
 
 The test suite contains a `fixtures` subdirectory, which is loaded as a `pytest` plugin when the tests are run.
 All `pytest.fixture` objects defined inside the `fixtures` subdirectory (and subdirectories therein) are discovered by `pytest`, and available for use by individual tests.
@@ -49,7 +102,7 @@ Our general guidelines for organising unit tests are:
 Any integration tests should be placed into the `test_integration` subfolder.
 Again, this directory should contain a single file per integration test.
 
-## Useful fixtures
+### Useful fixtures
 
 Some useful fixtures that are included in the `fixtures` directory;
 

mkdocs.yml

@@ -45,7 +45,7 @@ nav:
   - Users:
       - Graph: users/graph.md
   - Developers:
-      - Testing suite: developers/tests.md
+      - Contributing: developers/contributing.md
       - Graph: developers/graph.md
   - API reference: api.md
   - License: LICENSE.md

src/causalprog/algorithms/do.py

@@ -11,16 +11,16 @@ def get_included_excluded_successors(
     """
     Split successors of a node into nodes included and not included in a list.
 
-    Split the successorts of a node into a list of nodes that are included in
+    Split the successors of a node into a list of nodes that are included in
     the input node list and a list of nodes that are not in the list.
 
     Args:
-        graph: The graph
-        node_list: A dictionary of nodes, indexed by label
-        successors_of: The node to check the successors of
+        graph: The graph.
+        node_list: A dictionary of nodes, indexed by label.
+        successors_of: The node to check the successors of.
 
     Returns:
-        Lists of included and excluded nodes
+        Lists of included and excluded nodes.
 
     """
     included = []
@@ -38,11 +38,11 @@ def removable_nodes(graph: Graph, nodes: dict[str, Node]) -> tuple[str, ...]:
     Generate list of nodes that can be removed from the graph.
 
     Args:
-        graph: The graph
-        nodes: A dictionary of nodes, indexed by label
+        graph: The graph.
+        nodes: A dictionary of nodes, indexed by label.
 
     Returns:
-        List of labels of removable nodes
+        List of labels of removable nodes.
 
     """
     removable: list[str] = []
@@ -55,16 +55,16 @@ def removable_nodes(graph: Graph, nodes: dict[str, Node]) -> tuple[str, ...]:
 
 def do(graph: Graph, node: str, value: float, *, label: str | None = None) -> Graph:
     """
-    Apply do to a graph.
+    Apply `do` to a graph.
 
     Args:
         graph: The graph to apply do to. This will be copied.
         node: The label of the node to apply do to.
         value: The value to set the node to.
-        label: The label of the new graph
+        label: The label of the new graph.
 
     Returns:
-        A copy of the graph with do applied
+        A copy of the graph with do applied.
 
     """
     if label is None:

src/causalprog/algorithms/moments.py

@@ -14,7 +14,20 @@ def sample(
     parameter_values: dict[str, float] | None = None,
     rng_key: jax.Array,
 ) -> npt.NDArray[float]:
-    """Sample data from (a random variable attached to) a node in a graph."""
+    """
+    Sample data from (a random variable attached to) a node in a graph.
+
+    Args:
+        graph: The graph from which to sample.
+        outcome_node_label: The label of the node to sample from.
+        samples: Number of desired samples.
+        parameter_values: Values to be taken by node parameters.
+        rng_key: PRNG key to use to generate samples.
+
+    Returns:
+        Array of `samples` elements, containing the random samples.
+
+    """
     nodes = graph.roots_down_to_outcome(outcome_node_label)
 
     values: dict[str, npt.NDArray[float]] = {}
@@ -38,7 +51,20 @@ def expectation(
     parameter_values: dict[str, float] | None = None,
     rng_key: jax.Array,
 ) -> float:
-    """Estimate the expectation of (a random variable attached to) a node in a graph."""
+    """
+    Estimate the expectation of (a random variable attached to) a node in a graph.
+
+    Args:
+        graph: The graph containing the node.
+        outcome_node_label: The label of the node to compute the expectation of.
+        samples: Number of samples to use to estimate the expectation.
+        parameter_values: Values to be taken by node parameters.
+        rng_key: PRNG key to use to generate samples.
+
+    Returns:
+        Approximation to the expectation of `outcome_node_label`.
+
+    """
     return moment(
         1,
         graph,
@@ -58,7 +84,26 @@ def standard_deviation(
     rng_key: jax.Array,
     rng_key_first_moment: jax.Array | None = None,
 ) -> float:
-    """Estimate the standard deviation of (a RV attached to) a node in a graph."""
+    r"""
+    Estimate the standard deviation of (a RV attached to) a node in a graph.
+
+    The method computes the standard deviation of node $X$ via the formula
+
+    $$ \sqrt{\mathrm{Var}(X)} = \sqrt{\mathbb{E}[X^2] - \mathbb{E}[X]^2}. $$
+
+    Args:
+        graph: The graph containing the node.
+        outcome_node_label: The label of the node to compute the standard deviation of.
+        samples: Number of samples to use to estimate the standard deviation.
+        parameter_values: Values to be taken by node parameters.
+        rng_key: PRNG key to use to generate samples.
+        rng_key_first_moment: PRNG key that will be used to approximate the expectation,
+            used in the formula to calculate the standard deviation.
+
+    Returns:
+        Approximation to the standard deviation of `outcome_node_label`.
+
+    """
     return (
         moment(
             2,
@@ -89,7 +134,21 @@ def moment(
     parameter_values: dict[str, float] | None = None,
     rng_key: jax.Array,
 ) -> float:
-    """Estimate a moment of (a random variable attached to) a node in a graph."""
+    """
+    Estimate a moment of (a random variable attached to) a node in a graph.
+
+    Args:
+        order: Order of the moment to estimate.
+        graph: The graph containing the node.
+        outcome_node_label: The label of the node to compute the moment of.
+        samples: Number of samples to be used to estimate the moment.
+        parameter_values: Values to be taken by node parameters.
+        rng_key: PRNG key to use to generate samples.
+
+    Returns:
+        Approximation to the `order` moment of `outcome_node_label`.
+
+    """
     return (
         sum(
             sample(

src/causalprog/causal_problem/causal_problem.py

@@ -14,7 +14,6 @@
 from causalprog.graph import Graph
 
 
-# TODO: https://github.com/UCL/causalprog/issues/88
 def sample_model(
     model: Predictive, rng_key: jax.Array, parameter_values: dict[str, npt.ArrayLike]
 ) -> dict[str, npt.ArrayLike]:

src/causalprog/graph/continuous_treatment.py

@@ -255,19 +255,14 @@ def build_causal_response_function(
     `xl` contains the fixed values of `x` and `l`. The latent variable
     `u_y` is supplied internally by the quadrature rule.
 
-    Parameters
-    ----------
-    graph : Graph
-        Ricardo's causal graph.
-    quadrature : QuadratureMethod
-        Quadrature rule used to evaluate the expectation over the
-        standard-normal latent variable $U_Y$.
-
-    Returns
-    -------
-    Callable
+    Args:
+        graph: Graph representing a continuous treatment model.
+        quadrature: Quadrature rule used to evaluate the expectation over the
+            standard-normal latent variable $U_Y$.
+
+    Returns:
         A callable that evaluates the causal response function
-        $d(x, l; \theta)$.
+            $d(x, l; \theta)$.
 
     """
     if not isinstance(quadrature, UWMCGQuad):
@@ -304,7 +299,7 @@ def _d(
         $$
         d(x, l; \theta)
         =
-        \mathbb{E}[Y \mid \operatorname{do}(X=x), L=l].
+        \mathbb{E}[Y \mid \mathrm{do}(X=x), L=l].
         $$
         """
         return quadrature.integrate(
@@ -391,6 +386,9 @@ def build_loss_function(
         evaluation_points_axes_mapping: Axes to vectorise over when evaluating $r$
             at the `evaluation_points`.
 
+    Returns:
+        Callable that evaluates $B(\theta)$.
+
     """
     if r_hat_i.ndim != 1:
         msg = f"`r_hat_i` must be a 1D array (got {r_hat_i.shape})"