IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

Clarify documentation on use of doctest extension

Browse Source 
When I first read this section, I was mightily confused due to lack of context and the use of the passive voice.
I think this phrasing clarifies the context and indicates more clearly what the documentation author does
vs what the doctest extension and builder do.
But I'm a newbie here, so please ensure that I got this right....
This commit is contained in:
Neal McBurnett 2020-02-09 16:59:39 -07:00 committed by GitHub
parent 6e0119526a
commit 9b125cf8e9
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 8 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
doc/usage/extensions/doctest.rst
View File

@ -11,11 +11,15 @@
pair: testing; snippets pair: testing; snippets
This extension allows you to test snippets in the documentation in a natural It is often helpful to include snippets of code in your documentation and
way. It works by collecting specially-marked up code blocks and running them as demonstrate the results of executing it. But it is important to ensure that
doctest tests. the documentation stays up-to-date with the code.
Within one document, test code is partitioned in *groups*, where each group This extension allows you to test such code snippets in the documentation in
a natural way. If you mark the code blocks as shown here, the ``doctest''
builder will collect them and run them as doctest tests.
Within each document, you can assign each snippet to a *group*. Each group
consists of: consists of:
* zero or more *setup code* blocks (e.g. importing the module to test) * zero or more *setup code* blocks (e.g. importing the module to test)