From 9b125cf8e9050159f942023ba6a90b240b6e7385 Mon Sep 17 00:00:00 2001 From: Neal McBurnett Date: Sun, 9 Feb 2020 16:59:39 -0700 Subject: [PATCH] Clarify documentation on use of doctest extension 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.... --- doc/usage/extensions/doctest.rst | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/doc/usage/extensions/doctest.rst b/doc/usage/extensions/doctest.rst index 79a75536e..8c6740c26 100644 --- a/doc/usage/extensions/doctest.rst +++ b/doc/usage/extensions/doctest.rst @@ -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)