Cleanup

Author: raffaelemancuso

.github/workflows/docs.yml

@@ -0,0 +1,21 @@
+name: docs
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+jobs:
+  doctest:
+    name: Documentation doctests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Run documentation doctests
+        run: >-
+          uv run --extra docs --extra pandas --extra polars
+          sphinx-build -b doctest docs/source docs/_build/doctest

.gitignore

@@ -1,6 +1,7 @@
 __pycache__
 old/
 /docs/build
+/docs/_build
 /docs/source/*
 !/docs/source/*.rst
 !/docs/source/conf.py

README.md

@@ -47,7 +47,6 @@ only pull in what you use:
 | `pandas`         | `raffalib.pandas` accessors                          |
 | `polars`         | `raffalib.polars` accessors and join logging         |
 | `bibliometrics`  | OpenAlex / Scopus helpers                            |
-| `crypto`         | KeePassXC / GnuPG helpers                            |
 | `db`             | SQLAlchemy view helpers                              |
 | `web`            | Selenium helpers                                     |
 | `docs`           | Build the Sphinx documentation                       |
@@ -69,7 +68,7 @@ import raffalib.pandas  # registers the `.raffa` accessor
 
 logger = raffalib.create_logger(rich=False, fmt="{message}")
 
-df = pd.read_csv("penguins.csv")
+df = pd.read_csv("https://raw.githubusercontent.com/allisonhorst/palmerpenguins/refs/heads/main/inst/extdata/penguins.csv")
 
 # Shape changes are logged automatically
 _ = df.raffa.startlog().dropna(subset=["bill_depth_mm"]).raffa.endlog(timeit=False)
@@ -89,7 +88,7 @@ import raffalib.polars  # registers the `.raffa` namespace
 
 logger = raffalib.create_logger(rich=False, fmt="{message}")
 
-df = pl.read_csv("penguins.csv")
+df = pl.read_csv("https://raw.githubusercontent.com/allisonhorst/palmerpenguins/refs/heads/main/inst/extdata/penguins.csv")
 
 _ = df.raffa.startlog().filter(pl.col("species") == "Adelie").raffa.endlog(timeit=False)
 # -> Removed 192/344 (55.81%) rows.
@@ -153,6 +152,15 @@ uv run ruff check    # lint
 uv run ruff format   # format
 ```
 
+The examples in the documentation (`docs/source/quickstart.rst` and
+`examples.rst`) are executable doctests. They run in CI and can be checked
+locally with:
+
+```console
+uv run --extra docs --extra pandas --extra polars \
+  sphinx-build -b doctest docs/source docs/_build/doctest
+```
+
 ## License
 
 Released under the [GNU General Public License v3.0 or later](LICENSE.txt).

docs/source/conf.py

@@ -26,11 +26,53 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
 extensions = [
-    'autoapi.extension'
+    'autoapi.extension',
+    'sphinx.ext.doctest',
 ]
 
 autoapi_dirs = ['../../src']
 
+# -- doctest configuration ---------------------------------------------------
+# The examples in the narrative docs are executable doctests, run with
+# ``sphinx-build -b doctest`` (``make doctest``). ELLIPSIS lets the
+# non-deterministic ``Took: ...`` timing lines match; NORMALIZE_WHITESPACE makes
+# the DataFrame/table reprs robust to incidental spacing differences.
+import doctest as _doctest
+
+doctest_default_flags = _doctest.ELLIPSIS | _doctest.NORMALIZE_WHITESPACE
+
+# Run once before every doctest group: import the libraries, route raffalib's
+# logging output to stdout so doctest can capture it (mirroring
+# ``create_logger(rich=False, fmt="{message}")``), and pin the table-rendering
+# width so the captured reprs are deterministic.
+doctest_global_setup = """
+import logging
+import numpy as np
+import pandas as pd
+import polars as pl
+import polars.selectors as cs
+import raffalib
+import raffalib.pandas
+import raffalib.polars
+
+
+class _DoctestLogHandler(logging.Handler):
+    def emit(self, record):
+        print(self.format(record))
+
+
+_handler = _DoctestLogHandler()
+_handler.setFormatter(logging.Formatter("%(message)s"))
+_raffalogger = logging.getLogger("raffalib")
+_raffalogger.handlers = [_handler]
+_raffalogger.setLevel(logging.INFO)
+_raffalogger.propagate = False
+
+pd.set_option("display.max_columns", None)
+pd.set_option("display.width", 200)
+pl.Config(thousands_separator=",", tbl_cols=-1, tbl_width_chars=200)
+"""
+
 # Document the class docstring and the __init__ docstring together.
 autoapi_python_class_content = "both"