Test readme#390
Open
tschm wants to merge 14 commits intoplotly:masterfrom
Open
Conversation
gvwilson
added
feature
There was a problem hiding this comment.
Pull request overview
Adds automated validation for Python examples in the documentation by converting README code fences to doctest-compatible snippets and introducing a pytest that executes them.
Changes:
- Added a pytest that extracts
```pythonblocks fromREADME.mdand runs them viadoctest. - Updated
src/py/README.mdPython examples to doctest prompt style (>>>,...) so they can be executed as tests.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.
| File | Description |
|---|---|
src/py/tests/test_readme.py |
New test to extract README Python blocks and execute them via doctest. |
src/py/README.md |
Updates Python code fences to doctest format to support execution/validation. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+124
to
+135
| try: | ||
| # Run the code examples through doctest | ||
| doctest.run_docstring_examples(docstring, globals()) | ||
| except doctest.DocTestFailure as e: | ||
| # If a DocTestFailure occurs, capture it and manually fail the test | ||
| pytest.fail(f"Doctests failed: {e}") | ||
|
|
||
| # Capture the output after running doctests | ||
| captured = capfd.readouterr() | ||
|
|
||
| # If there is any output (error message), fail the test | ||
| if captured.out: |
Comment on lines
+90
to
+102
| # Extract Python code blocks (assuming they are in triple backticks) | ||
| blocks = re.findall(r"```python(.*?)```", content, re.DOTALL) | ||
|
|
||
| code = "\n".join(blocks).strip() | ||
|
|
||
| # Add a docstring wrapper for doctest to process the code | ||
| docstring = f"\n{code}\n" | ||
|
|
||
| return docstring | ||
|
|
||
| except FileNotFoundError: | ||
| warnings.warn("README.md file not found", stacklevel=2) | ||
| return "" |
Comment on lines
+131
to
+136
| # Capture the output after running doctests | ||
| captured = capfd.readouterr() | ||
|
|
||
| # If there is any output (error message), fail the test | ||
| if captured.out: | ||
| pytest.fail(f"Doctests failed with:\n{captured.out} and \n{docstring}") |
Comment on lines
+67
to
+92
| return find_project_root(Path(__file__).parent) | ||
|
|
||
|
|
||
| @pytest.fixture | ||
| def docstring(project_root: Path) -> str: | ||
| """Extract Python code blocks from README.md and prepare them for doctest. | ||
|
|
||
| This fixture reads the README.md file, extracts all Python code blocks | ||
| (enclosed in triple backticks with 'python' language identifier), and | ||
| combines them into a single docstring that can be processed by doctest. | ||
|
|
||
| Args: | ||
| project_root: Path to the project root directory | ||
|
|
||
| Returns: | ||
| str: A docstring containing all Python code examples from README.md | ||
|
|
||
| """ | ||
| # Read the README.md file | ||
| try: | ||
| with Path.open(project_root / "README.md", encoding="utf-8") as f: | ||
| content = f.read() | ||
|
|
||
| # Extract Python code blocks (assuming they are in triple backticks) | ||
| blocks = re.findall(r"```python(.*?)```", content, re.DOTALL) | ||
|
|
Comment on lines
+121
to
+123
| # Change to the root directory to ensure imports work correctly | ||
| os.chdir(project_root) | ||
|
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.