Turn on basic doctests for modules and .rst docs #511
Conversation
drewoldag
left a comment
drewoldag
left a comment
There was a problem hiding this comment.
The PPT can create example modules - it might make sense to include a doctest in one or both of the example functions.
hombit
left a comment
hombit
left a comment
There was a problem hiding this comment.
Looks great, thank you! There is one comment only, maybe you meant to put a different link for .rst-doctest examples.
| `doctest <https://doc.pytest.org/en/latest/how-to/doctest.html>`_ component. | ||
| Documentation comments in all source files, as well as ``.rst`` files in the ``./docs`` | ||
| directory can contain doctests in the format outlined | ||
| `here <https://doc.pytest.org/en/latest/how-to/doctest.html>`_. |
There was a problem hiding this comment.
Should it be some other link?
There was a problem hiding this comment.
I'm not sure there's a better one. This change doesn't include anything .rst specific, so you just have to use the normal syntax in your .rst files.
AFAICT that one page is the only obviously authoritative place on the internet that explains the syntax. If we somehow do something special and more .rst friendly we could amend this.
There was a problem hiding this comment.
Doctest is a part of PEP287, and it is support by the standard library's doctest module. So pytest docs is not the only authoritative place...
Just added this. |
Change Description
Addressing #379.
Turning on doctest by default in ppt. This base configuration will:
.rstfiles that use the>>>syntaxThis is not particularly fancy, but will give a "batteries included" setup to anyone who wants to use doctests.
I have added a little bit of documentation, but it feels like its too far at the leaf of a documentation tree for anyone to find.
Perhaps this is okay?
Checklist
lincc-frameworks/python-project-templaterepo and not a downstream one instead.