Include explanation about doctests

1 files changed, 5 insertions, 0 deletions

diff --git a/doc/tutorial/describing-code.rst b/doc/tutorial/describing-code.rst
index b1817b2b7..8988a8190 100644
--- a/doc/tutorial/describing-code.rst
+++ b/doc/tutorial/describing-code.rst
@@ -212,6 +212,11 @@ Then, write a doctest block as follows:
    >>> lumache.get_random_ingredients()
    ['shells', 'gorgonzola', 'parsley']
 
+Doctests include the Python instructions to be run preceded by ``>>>``,
+the standard Python interpreter prompt, as well as the expected output
+of each instruction. This way, Sphinx can check whether the actual output
+matches the expected one.
+
 To observe how a doctest failure looks like (rather than a code error as
 above), let's write the return value incorrectly first. Therefore, add a
 function ``get_random_ingredients`` like this: