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

Simplify doctest section

Browse Source
This commit is contained in:
Juan Luis Cano Rodríguez
2021-09-06 16:32:54 +02:00
parent d505635224
commit 878478e725
1 changed files with 7 additions and 59 deletions
Download Patch File Download Diff File Expand all files Collapse all files

66
doc/tutorial/describing-code.rst
View File

@@ -212,51 +212,9 @@ Then, write a doctest block as follows:
>>> lumache.get_random_ingredients() >>> lumache.get_random_ingredients()
['shells', 'gorgonzola', 'parsley'] ['shells', 'gorgonzola', 'parsley']
You can now run ``make doctest`` to execute the doctests of your documentation. To observe how a doctest failure looks like (rather than a code error as
However, initially this will display an error, since the actual code does not above), let's write the return value incorrectly first. Therefore, add a
exist yet: function ``get_random_ingredients`` like this:
.. code-block:: console
(.venv) $ make doctest
Running Sphinx v4.2.0+
loading pickled environment... done
...
running tests...
Document: usage
---------------
**********************************************************************
File "usage.rst", line 44, in default
Failed example:
lumache.get_random_ingredients()
Exception raised:
Traceback (most recent call last):
File "/usr/lib/python3.9/doctest.py", line 1336, in __run
exec(compile(example.source, filename, "single",
File "<doctest default[1]>", line 1, in <module>
lumache.get_random_ingredients()
AttributeError: module 'lumache' has no attribute 'get_random_ingredients'
**********************************************************************
1 items had failures:
1 of 2 in default
2 tests in 1 items.
1 passed and 1 failed.
***Test Failed*** 1 failures.
Doctest summary
===============
2 tests
1 failure in tests
0 failures in setup code
0 failures in cleanup code
build finished with problems.
make: *** [Makefile:20: doctest] Error 1
Therefore, you will need to make adjustments to your ``lumache.py``. 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:
.. code-block:: python .. code-block:: python
:caption: lumache.py :caption: lumache.py
@@ -264,7 +222,9 @@ write the return value incorrectly first. Therefore, add a function
def get_random_ingredients(): def get_random_ingredients():
return ["eggs", "bacon", "spam"] return ["eggs", "bacon", "spam"]
Now ``make doctest`` will give an output similar to this: You can now run ``make doctest`` to execute the doctests of your documentation.
Initially this will display an error, since the actual code does not behave
as specified:
.. code-block:: console .. code-block:: console
@@ -285,19 +245,7 @@ Now ``make doctest`` will give an output similar to this:
Got: Got:
['eggs', 'bacon', 'spam'] ['eggs', 'bacon', 'spam']
********************************************************************** **********************************************************************
1 items had failures: ...
1 of 2 in default
2 tests in 1 items.
1 passed and 1 failed.
***Test Failed*** 1 failures.
Doctest summary
===============
2 tests
1 failure in tests
0 failures in setup code
0 failures in cleanup code
build finished with problems.
make: *** [Makefile:20: doctest] Error 1 make: *** [Makefile:20: doctest] Error 1
As you can see, doctest reports the expected and the actual results, As you can see, doctest reports the expected and the actual results,