Update docs and change to mkdocs

.github/workflows/test_docs.yml

@@ -20,7 +20,7 @@ jobs:
     - name: install bibat with development packages
       run: pip install -e .\[development\]
     - name: build docs with sphinx
-      run: sphinx-build docs ./docs/_build/html/
+      run: mkdocs build
     - name: Audit with Lighthouse
       uses: treosh/lighthouse-ci-action@v10
       with:

.gitignore

@@ -1,4 +1,5 @@
-bibat/examples/**/idata/
+site
+bibat/example_projects/**/idata/
 .tox",
 __pycache__",
 .ipynb_checkpoints/",

.readthedocs.yaml

@@ -1,8 +1,7 @@
-# .readthedocs.yaml
-# Read the Docs configuration file
+# Read the Docs configuration file for MkDocs projects
 # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
-
 # Required
+
 version: 2
 
 # Set the version of Python and other tools you might need
@@ -11,20 +10,11 @@ build:
   tools:
     python: "3.12"
 
-# Build documentation in the docs/ directory with Sphinx
-sphinx:
-  configuration: docs/conf.py
-  fail_on_warning: true
-
-# If using Sphinx, optionally build your docs in additional formats such as PDF
-# formats:
-#    - pdf
+mkdocs:
+  configuration: mkdocs.yml
 
-# Optionally declare the Python requirements required to build your docs
 python:
-   install:
-    - method: pip
+  install:
       path: .
       extra_requirements:
         - development
-    - requirements: docs/requirements.txt

CONTRIBUTING.md

@@ -0,0 +1,64 @@
+# How to contribute to bibat
+
+All contributions are very welcome!
+
+Make sure to read the [code of conduct](https://github.com/teddygroves/bibat/CODE_OF_CONDUCT.md) and follow its recommendations.
+
+If you have a specific suggestion for how bibat could be improved, or if you
+find a bug then please file an issue or submit a pull request.
+
+Alternatively, if you have any more general thoughts or questions, please post
+them in the [discussions page](https://github.com/teddygroves/bibat/discussions).
+
+If you would like to contribute code changes, just follow the normal [GitHub
+workflow](https://docs.github.com/en/get-started/quickstart/github-flow):
+make a local branch with the changes then create a pull request.
+
+## Developing bibat locally
+
+To develop bibat locally you will probably need to install it with development
+dependencies. Here is how to do so:
+
+```sh
+$ pip install bibat'[development]'
+```
+
+You can see what these dependencies are by checking the
+`[project.optional-dependencies]` table in bibat's [`pyproject.toml` file](https://github.com/teddygroves/bibat/blob/main/pyproject.toml). Some
+important ones are [black](https://github.com/psf/black),
+[isort](https://pycqa.github.io/isort/),
+[pre-commit](https://pre-commit.com/) and [tox](https://tox.wiki/en/latest/).
+
+Another thing you will want to do while developing bibat locally is use it to
+create projects. For this I recommend avoiding having to complete the wizard
+every time by using copier's `--defaults` (abbreviation `-l`) [option](https://copier.readthedocs.io/en/stable/reference/cli/#copier.cli), e.g.
+
+```sh
+$ copier copy -l --vcs-ref HEAD bibat my_cool_project
+```
+
+## Cmdstan
+
+Bibat depends on [cmdstan](https://github.com/stan-dev/cmdstan), which can
+be tricky to install. If you run the commands `make env` or `make analysis`
+from a bibat project, it will attempt to install cmdstan automatically. If
+this doesn't work, please check the [cmdstan](https://mc-stan.org/users/interfaces/cmdstan) and [cmdstanpy](https://cmdstanpy.readthedocs.io/en/v1.1.0/installation.html#cmdstan-installation) documentation.
+
+## Releasing new versions of bibat
+
+To release a new version of bibat, edit the field `version` in the file
+`pyproject.toml`, e.g. to `0.2.1` then make a pull request with this change.
+
+Once the changes are merged into the `origin/main` branch, add a tag whose name
+begins with `v`, followed by the new version number to your local `main` branch,
+for example like this:
+
+```sh
+$ git tag v0.2.1
+```
+
+Now push the new tag to GitHub:
+
+```sh
+$ git push origin "v0.2.1"
+```

bibat/fitting_mode.py

@@ -27,24 +27,27 @@ class IdataTarget(str, Enum):
 class FittingMode(BaseModel):
     """A way of fitting a statistical model.
 
-    Each fitting mode has a name, an 'idata_target', i.e. the group that this
-    mode will create in the output InferenceData, and a function that performs
-    the fitting.
-
     Inferences can be configured to use any of the fitting modes defined here
     by including them by name in the top-level list 'modes'. For example:
 
+    ```toml
       ...
       modes = ['prior', 'posterior', 'kfold']
       ...
+    ```
 
-    The idata_target must be one out of 'prior', 'posterior' and
-    'log_likelihood', and specifies which out of these InferenceData groups the
-    output will be written to.
+    :param name: A string identifying the fitting mode
 
-    Each fitting mode's fit function must match the signature specified in the
-    FittingMode class.
+    :param idata_target: A string identifying the
+    [`InferenceData`](https://python.arviz.org/en/stable/api/inference_data.html)
+    group that the mode writes to. Must be one of "prior", "posterior" or
+    "log_likelihood".
 
+    :param fit: A function that takes in an `InferenceConfiguration` object, a
+    `PreparedData` object and a dictionary of local functions, and returns
+    either a CmdStanMCMC object (if the `idata_target` is "prior" or
+    "posterior") or an xarray DataArray object (if the `idata_target` is
+    "log_likelihood")
     """
 
     name: str

bibat/inference_configuration.py

@@ -1,4 +1,9 @@
-"""Definition of the InferenceConfiguration class."""
+"""The inference_configuration module.
+
+This module provides the class InferenceConfiguration and the function
+`load_inference_configuration`.
+
+"""
 
 from __future__ import annotations
 
@@ -12,13 +17,9 @@
 
 
 class InferenceConfiguration(BaseModel):
-    """Container for a path to a Stan model and some configuration.
+    """Configuration for a statistical inference.
 
-    For example, you may want to compare how well two stan programs fit the
-    same data, or how well the same model fits the data with different
-    covariates.
-
-    :param name: string name identifying the model configuration
+    :param name: A name identifying the model configuration
 
     :param stan_file: Path to a Stan program, with "/" even on windows
 
@@ -42,7 +43,6 @@ class InferenceConfiguration(BaseModel):
 
     :param stanc_options: valid choices for the `cpp_options` argument to
     CmdStanModel
-
     """
 
     name: str

bibat/util.py

@@ -1,12 +1,11 @@
-"""Some handy python functions."""
+"""A module that provides some Bayesian analysis oriented utility code."""
 
 from __future__ import annotations
 
 from collections.abc import Mapping
 from functools import wraps
 from typing import TYPE_CHECKING, Any, NewType, ParamSpec
 
-import numpy as np
 import pandas as pd
 from stanio.json import process_dictionary
 
@@ -59,52 +58,8 @@ def make_columns_lower_case(df: pd.DataFrame) -> pd.DataFrame:
 
 
 def check_is_df(maybe_df: Any) -> pd.DataFrame:  # noqa: ANN401
-    """Shut up the type checker."""
+    """Check that an object is a DataFrame."""
     if not isinstance(maybe_df, pd.DataFrame):
         msg = "Want dataframe."
         raise TypeError(msg)
     return maybe_df
-
-
-def stanify_dict(d: dict) -> StanInputDict:
-    """Make sure a dictionary is a valid Stan input.
-
-    :param d: input dictionary, possibly with wrong types
-    """
-    out: StanInputDict = {}
-    for k, v in d.items():
-        if not isinstance(k, str):
-            msg = f"key {k!r} is not a string!"
-            raise TypeError(msg)
-        if isinstance(v, pd.Series):
-            out[k] = v.to_list()
-        elif isinstance(v, pd.DataFrame):
-            out[k] = v.to_numpy().tolist()
-        elif isinstance(v, np.ndarray):
-            out[k] = v.tolist()
-        else:
-            out[k] = v
-    return out
-
-
-def standardise(
-    s: pd.Series,
-    mu: float | None = None,
-    std: float | None = None,
-) -> pd.Series:
-    """Standardise a series by subtracting mu and dividing by sd."""
-    if mu is None:
-        mu = s.mean()
-    if std is None:
-        std = s.std()
-    return s.subtract(mu).divide(std)
-
-
-def center(
-    s: pd.Series,
-    mu: float | None = None,
-) -> pd.Series:
-    """Center a series by subtracting mu."""
-    if mu is None:
-        mu = s.mean()
-    return s.subtract(mu)