📝 Add testing code to documentation

Author: veit

docs/document/test.rst

@@ -157,6 +157,32 @@ format can be checked with `sphinx-lint
    Sybil can also check code blocks in the documentation with either
    :doc:`../test/pytest/index` or :doc:`../test/unittest`.
 
+.. _test_code:
+
+Code
+----
+
+With the built-in Python library :doc:`../test/doctest`, you can also test code
+in your documentation with the :func:`doctest.testfile` method:
+
+.. code-block:: Python
+
+   import doctest
+
+   doctest.testfile("example.rst")
+
+This short script executes and checks all interactive Python examples contained
+in the :file:`example.rst` file. The content of the file is treated as if it
+were a single huge docstring.
+
+.. seealso::
+   A simple example can be found in the Python documentation: `Simple Usage:
+   Checking Examples in a Text File
+   <https://docs.python.org/3/library/doctest.html#simple-usage-checking-examples-in-a-text-file>`_.
+
+   Another way to test code in documentation is
+   `pytest-doctestplus <https://github.com/scientific-python/pytest-doctestplus>`_.
+
 Code formatting
 ---------------
 

docs/test/doctest.rst

@@ -1,8 +1,8 @@
 Doctest
 =======
 
-The Python module :doc:`doctest <python3:library/doctest>` checks whether the
-tests specified in a docstring are fulfilled.
+The Python module :doc:`doctest <python3:library/doctest>` checks whether tests
+in a docstring or in another text file are fulfilled.
 
 #. In :download:`arithmetic.py` you can add the following docstring:
 
@@ -114,3 +114,7 @@ tests specified in a docstring are fulfilled.
       :language: python
       :lines: 38-
       :lineno-start: 38
+
+.. seealso::
+   :doc:`doctest <python3:library/doctest>` also has the ability to execute
+   tests in your documentation: :ref:`Document → Testing → Code <test_code>`.