Documentation tests (#59)

Adds tests for the code blocks in the README and our user guides. Also, fixes one bug that got unveiled.

CHANGELOG.md

@@ -8,12 +8,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 - Target enums 
 - `mypy` for targets and intervals
+- Tests for code blocks in README and user guides
 
 ### Changed
 - Renamed `bounds_transform_func` target attribute to `transformation`
 - `Interval.is_bounded` now implements the mathematical definition of boundedness
 - Moved and renamed target transform utility functions
 
+### Fixed
+- Wrong use of `tolerance` argument in constraints user guide
+
 ### Removed
 - Conda install instructions and version badge
 

docs/userguide/constraints.md

@@ -100,7 +100,6 @@ from baybe.constraints import ThresholdCondition
 ThresholdCondition( # will select all values above 150
     threshold = 150, 
     operator = ">",
-    tolerance = 0.2 # optional, with this 149.82 would still be valid
 )
 ```
 

ruff.toml

@@ -26,6 +26,7 @@ extend-ignore = [
 "baybe/exceptions.py" = ["D205", "D212", "D415"]
 # Missing module docstrings in module/package
 "tests/__init__.py" =  ["D100", "D104"]
+"tests/docs/__init__.py" = ["D100", "D104"]
 "tests/serialization/__init__.py" = ["D100", "D104"]
 "tests/validation/__init__.py" = ["D100", "D104"]
 "docs/conf.py" = ["D100"]

tests/docs/test_docs.py

@@ -0,0 +1,20 @@
+"""Test the code provided in the docs."""
+
+from pathlib import Path
+
+import pytest
+
+from .utils import extract_code_blocks
+
+
+def test_readme():
+    """The blocks in the README become a valid python script when concatenated."""
+    readme_code = extract_code_blocks("README.md")
+    exec(readme_code)
+
+
+@pytest.mark.parametrize("file", Path("docs/userguide/").rglob("*.md"))
+def test_userguide(file: Path):
+    """The blocks in the user guide become a valid python script when concatenated."""
+    userguide_code = extract_code_blocks(file)
+    exec(userguide_code)

tests/docs/test_examples.py

@@ -0,0 +1,21 @@
+"""Test if all examples can be run without error."""
+
+import runpy
+from pathlib import Path
+
+import pytest
+
+from baybe.surrogates import _ONNX_INSTALLED
+from baybe.utils.chemistry import _MORDRED_INSTALLED, _RDKIT_INSTALLED
+
+_CHEM_INSTALLED = _MORDRED_INSTALLED and _RDKIT_INSTALLED
+
+
+@pytest.mark.slow
+@pytest.mark.skipif(
+    not (_CHEM_INSTALLED and _ONNX_INSTALLED), reason="skipped for core tests"
+)
+@pytest.mark.parametrize("example", Path("examples/").rglob("*.py"))
+def test_example(example: Path):
+    """Test an individual example by running it."""
+    runpy.run_path(str(example))

tests/docs/utils.py

@@ -0,0 +1,14 @@
+"""Utilities for doc testing."""
+
+import re
+from pathlib import Path
+from typing import Union
+
+
+def extract_code_blocks(path: Union[str, Path]) -> str:
+    """Extract all python code blocks from the specified file into a single string."""
+    contents = Path(path).read_text()
+    code_blocks = re.findall(r"```python\s+(.*?)\s+```", contents, flags=re.DOTALL)
+    concatenated_code = "\n".join(code_blocks)
+
+    return concatenated_code