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
This extension allows you to test snippets in the documentation in a natural
way. It works by collecting specially-marked up code blocks and running them as
doctest tests.
It is often helpful to include snippets of code in your documentation and
demonstrate the results of executing it. But it is important to ensure that
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:
* zero or more *setup code* blocks (e.g. importing the module to test)