Test Python docstring in markdown files

conftest.py

@@ -0,0 +1,8 @@
+import pytest
+
+from fio_planet import snuggs
+
+
+@pytest.fixture(autouse=True)
+def add_snuggs(doctest_namespace):
+    doctest_namespace["snuggs"] = snuggs

docs/expressions.md

@@ -19,7 +19,15 @@ includes:
 Expressions are evaluated by `fio_planet.features.snuggs.eval()`. Let's look at
 some examples using that function.
 
-Note: the outer parentheses are not optional within `snuggs.eval()`.
+!!! note
+
+    The outer parentheses are not optional within `snuggs.eval()`.
+
+!!! note
+
+    `snuggs.eval()` does not use Python's builtin `eval()` but isn't intended
+    to be a secure computing environment. Expressions which access the
+    computer's filesystem and create new processes are possible.
 
 ## Builtin Python functions
 
@@ -28,27 +36,31 @@ Note: the outer parentheses are not optional within `snuggs.eval()`.
 ```python
 >>> snuggs.eval('(bool 0)')
 False
+
 ```
 
 `range`:
 
 ```python
 >>> snuggs.eval('(range 1 4)')
 range(1, 4)
+
 ```
 
 `list`:
 
 ```python
 >>> snuggs.eval('(list (range 1 4))')
 [1, 2, 3]
+
 ```
 
 Values can be bound to names for use in expressions.
 
 ```python
 >>> snuggs.eval('(list (range start stop))', start=0, stop=5)
 [0, 1, 2, 3, 4]
+
 ```
 
 ## Itertools functions
@@ -58,6 +70,7 @@ Here's an example of using `itertools.repeat()`.
 ```python
 >>> snuggs.eval('(list (repeat "*" times))', times=6)
 ['*', '*', '*', '*', '*', '*']
+
 ```
 
 ## Shapely functions
@@ -67,13 +80,15 @@ Here's an expression that evaluates to a Shapely Point instance.
 ```python
 >>> snuggs.eval('(Point 0 0)')
 <POINT (0 0)>
+
 ```
 
 The expression below evaluates to a MultiPoint instance.
 
 ```python
 >>> snuggs.eval('(union (Point 0 0) (Point 1 1))')
 <MULTIPOINT (0 0, 1 1)>
+
 ```
 
 ## Functions specific to fio-planet
@@ -91,20 +106,23 @@ geometries.
 <GEOMETRYCOLLECTION (POINT (0 0), POINT (1 1))>
 >>> snuggs.eval('(list (dump (collect (Point 0 0) (Point 1 1))))')
 [<POINT (0 0)>, <POINT (1 1)>]
+
 ```
 
 The `identity` function returns its single argument.
 
 ```python
 >>> snuggs.eval('(identity 42)')
 42
+
 ```
 
 To count the number of vertices in a geometry, use `vertex_count`.
 
 ```python
 >>> snuggs.eval('(vertex_count (Point 0 0))')
 1
+
 ```
 
 The `area`, `buffer`, `distance`, `length`, `simplify`, and `set_precision`
@@ -119,6 +137,7 @@ longitude and latitude degrees, by a given distance in meters.
 ```python
 >>> snuggs.eval('(buffer (Point 0 0) :distance 100)')
 <POLYGON ((0.001 0, 0.001 0, 0.001 0, 0.001 0, 0.001 -0.001, 0.001 -0.001, 0...>
+
 ```
 
 The `area` and `length` of this polygon have units of square meter and meter.
@@ -128,13 +147,15 @@ The `area` and `length` of this polygon have units of square meter and meter.
 31214.451487413342
 >>> snuggs.eval('(length (buffer (Point 0 0) :distance 100))')
 627.3096977558143
+
 ```
 
 The `distance` between two geometries is in meters.
 
 ```python
 >>> snuggs.eval('(distance (Point 0 0) (Point 0.1 0.1))')
 15995.164946207413
+
 ```
 
 A geometry can be simplified to a tolerance value in meters using `simplify`.
@@ -144,6 +165,7 @@ There are more examples of this function under
 ```python
 >>> snuggs.eval('(simplify (buffer (Point 0 0) :distance 100) :tolerance 100)')
 <POLYGON ((0.001 0, 0 -0.001, -0.001 0, 0 0.001, 0.001 0))>
+
 ```
 
 The `set_precision` function snaps a geometry to a fixed precision grid with a
@@ -152,6 +174,7 @@ size in meters.
 ```python
 >>> snuggs.eval('(set_precision (Point 0.001 0.001) :grid_size 500)')
 <POINT (0 0)>
+
 ```
 
 ## Feature and geometry context for expressions
@@ -172,3 +195,9 @@ geometries using Shapely's `unary_union`.
 ```lisp
 unary_union c
 ```
+
+## Snippet test
+
+```python
+--8<-- "tests/test_cli.py:map"
+```

mkdocs.yml

@@ -68,6 +68,9 @@ nav:
   - "Topics": 'topics'
 
 markdown_extensions:
+  - pymdownx.inlinehilite
+  - pymdownx.snippets:
+      dedent_subsections: True
   - pymdownx.highlight
   - pymdownx.superfences
   - mkdocs-click

pyproject.toml

@@ -53,3 +53,4 @@ filterwarnings = [
     "ignore:.*pkg_resources is deprecated as an API",
     "ignore:.*module \\'sre_constants\\' is deprecated",
 ]
+doctest_optionflags = "NORMALIZE_WHITESPACE"

tests/test_cli.py

@@ -25,16 +25,18 @@ def test_map_count():
     with open("tests/data/trio.seq") as seq:
         data = seq.read()
 
+    # --8<-- [start:map]
     runner = CliRunner()
     result = runner.invoke(
         main_group,
         ["map", "centroid (buffer g 1.0)"],
-        input=data,
+        input=data, foo=42,
     )
+    # --8<-- [end:map]
+
     assert result.exit_code == 0
     assert result.output.count('"type": "Point"') == 3
 
-
 @pytest.mark.parametrize("raw_opt", ["--raw", "-r"])
 def test_reduce_area(raw_opt):
     """Reduce features to their (raw) area."""

tox.ini

@@ -7,7 +7,7 @@ envlist =
 deps =
     pytest-cov
 commands = 
-    python -m pytest -v --cov fio_planet --cov-report term-missing --pdb
+    python -m pytest -v --cov fio_planet --cov-report term-missing --doctest-glob="*.md"
 
 [gh-actions]
 python =