chore/doctests #3500
chore/doctests #3500
Conversation
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #3500 +/- ##
=======================================
Coverage 61.86% 61.86%
=======================================
Files 85 85
Lines 10111 10111
=======================================
Hits 6255 6255
Misses 3856 3856
🚀 New features to boost your workflow:
|
|
closes #3498 |
There was a problem hiding this comment.
@d-v-b do you have a vision for how to match the executed code output to the expected results? Currently, I think this PR is a more complicated version of mkdocs build --strict so without a clear path to output comparisons I don't find it super compelling
changes/3357.feature.md
Outdated
| @@ -0,0 +1 @@ | |||
| Adds `zarr.experimental.cache_store.CacheStore`, a `Store` that implements caching by combining two other `Store` instances. See the [docs page](https://zarr.readthedocs.io/en/latest/user-guide/cache-store) for more information about this feature. No newline at end of file | |||
There was a problem hiding this comment.
@d-v-b can you please remove this addition? It is already properly documented using the PR number in https://github.com/zarr-developers/zarr-python/blob/main/changes/3366.feature.md
But you reminded me that this PR can be made much simpler with |
github-actions
bot
added
the
needs release notes
It was not as simple as I thought -- the fact that our docs uses code blocks organized into sessions requires the test machinery in this PR. Since the examples in our docs are not currently set up for output checking, I left those tests as-is, but included a commented code block that, once commented, will check example code output. I also added a test for examples defined in our docstrings. We have some docstring examples that either require session logic (like the examples in our docs) or require a re-write, so I largely left those alone. I did fix #3503 though, and many other broken docstring examples. |
| # result = eval_example.run_print_check(example, module_globals=module_globals) | ||
| result = eval_example.run(example, module_globals=module_globals) |
There was a problem hiding this comment.
@maxrjones switching eval_example.run to eval_example.run_print_check will turn on output checks for the docs.
| async_arr = await AsyncArray.open(store) | ||
| return async_arr | ||
| async_arr = asyncio.run(example()) |
There was a problem hiding this comment.
our async examples previously used top-level await, which is not generally available in python interpreters. We now use asyncio.run()
Adds doctests. This PR builds atop #3366, and so should not be merged until #3366 is in.
I add a new test file in
test/test_docs.pythat collects executable examples and runs them, ensuring that no errors are raised.The goal here is to go from 0 doctests to some doctests. But we need to ultimately do more than "some doctests". We need tests that compare the output of the executed code against what we expected. I'm happy to take that as a contribution / addition to this PR if it's simple, or we can do that in a subsequent PR.