Test example.py and example.pyi blocks in user guide

Author: lagru

doc/command_line_reference.md

@@ -6,7 +6,7 @@ docstub --help
 ```
 will print
 
-<!--- Changes to the following block are overridden by the test suite --->
+<!--- The following block is checked by the test suite --->
 <!--- begin command-line-help --->
 
 ```plain

doc/user_guide.md

@@ -20,8 +20,11 @@ If you want to pin to a certain commit you can append `@COMMIT_SHA` to the repo
 
 Consider a simple example with the following documented function
 
+<!--- The following block is checked by the test suite --->
+<!--- begin example.py --->
+
 ```python
-# src/example.py
+# example.py
 
 def example_metric(image, *, mask=None, sigma=1.0, method='standard'):
     """Pretend to calculate a local metric between two images.
@@ -45,6 +48,8 @@ def example_metric(image, *, mask=None, sigma=1.0, method='standard'):
     pass
 ```
 
+<!--- end example.py --->
+
 Feeding this input to docstub with
 
 ```shell
@@ -53,6 +58,8 @@ docstub simple_script.py
 
 will create `example.pyi` in the same directory
 
+<!--- The following block is checked by the test suite --->
+<!--- begin example.pyi --->
 ```python
 # File generated with docstub
 
@@ -70,6 +77,7 @@ def example_metric(
     method: Literal["standard", "modified"] = ...
 ) -> NDArray[float]: ...
 ```
+<!--- end example.pyi --->
 
 There are several interesting things to note here:
 

tests/test_doc.py

@@ -5,27 +5,67 @@
 
 import click
 
-from docstub._cli import main
+from docstub._cli import main as docstub_main
 
 PROJECT_ROOT = Path(__file__).parent.parent
 
 
+def test_getting_started_example(tmp_path):
+    # Load user guide
+    md_file = PROJECT_ROOT / "doc/user_guide.md"
+    with md_file.open("r") as io:
+        md_content = io.read()
+
+    # Extract code block for example.py
+    regex_py = (
+        r"<!--- begin example.py --->"
+        r"\n```python\n(.*)\n```\n"
+        r"<!--- end example.py --->"
+    )
+    matches_py = re.findall(regex_py, md_content, flags=re.DOTALL)
+    assert len(matches_py) == 1
+    py_source = matches_py[0]
+
+    # Create example.py and run docstub on it
+    py_file = tmp_path / "example.py"
+    with py_file.open("x") as io:
+        io.write(py_source)
+    docstub_main([str(py_file)], standalone_mode=False)
+
+    # Load created PYI file, this is what we expect to find in the user guide's
+    # code block for example.pyi
+    pyi_file = py_file.with_suffix(".pyi")
+    assert pyi_file.is_file()
+    with pyi_file.open("r") as io:
+        expected_pyi = io.read().strip()
+
+    # Extract code block for example.pyi from guide
+    regex_pyi = (
+        r"<!--- begin example.pyi --->"
+        r"\n```python\n(.*)\n```\n"
+        r"<!--- end example.pyi --->"
+    )
+    matches_pyi = re.findall(regex_pyi, md_content, flags=re.DOTALL)
+    assert len(matches_pyi) == 1
+    actual_pyi = matches_pyi[0].strip()
+
+    assert expected_pyi == actual_pyi
+
+
 def test_command_line_help():
-    ctx = click.Context(main, info_name="docstub")
+    ctx = click.Context(docstub_main, info_name="docstub")
     expected_help = f"""
-
 ```plain
-{main.get_help(ctx)}
+{docstub_main.get_help(ctx)}
 ```
-
-"""
+""".strip()
     md_file = PROJECT_ROOT / "doc/command_line_reference.md"
     with md_file.open("r") as io:
         md_content = io.read()
 
     regex = r"<!--- begin command-line-help --->(.*)<!--- end command-line-help --->"
-    match = re.findall(regex, md_content, flags=re.DOTALL)
-    assert len(match) == 1
+    matches = re.findall(regex, md_content, flags=re.DOTALL)
+    assert len(matches) == 1
 
-    actual_help = match[0]
+    actual_help = matches[0].strip()
     assert actual_help == expected_help