Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Use sybil to run code in tutorials #1487

Open
bhazelton opened this issue Oct 15, 2024 · 0 comments
Open

Use sybil to run code in tutorials #1487

bhazelton opened this issue Oct 15, 2024 · 0 comments
Labels
docs documentation

Comments

@bhazelton
Copy link
Member

On a recent PR I realized that sphinx code-blocks without the >>> doctest prefix weren't being run by our existing doctests. After some searching, I found a pytest page that suggested using Sybil.

Sybil (https://sybil.readthedocs.io/en/latest/) works with pytest to find and run code-block and doctest blocks in sphinx docs. I played with it a bit and it's great. One really nice feature is that it gives each block to pytest separately so you even if one block fails it runs all the others and the information about what failed is easier to find and parse.

Our existing tutorials do have some mistakes that trip up Sybil -- we have blocks that are marked as code-block but written with the >>> prefix which should only be used for doctest blocks. So we'll have to fix those. We should also think a bit about where to use code-block vs doctest vs testcode andtestoutput pair blocks. More details on these are in the documentation on sphinx doctest (sybil respects all of these, including hidden asserts): https://www.sphinx-doc.org/en/master/usage/extensions/doctest.html

I also didn't have much luck using sybil with pytest-xdist, but I haven't dug into the issues there much.

@bhazelton bhazelton added the docs documentation label Oct 15, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs documentation
Projects
None yet
Development

No branches or pull requests

1 participant