From ea49b14409038271543fec16b8b9255a151d992a Mon Sep 17 00:00:00 2001 From: Chris Pyles Date: Sat, 6 Nov 2021 17:55:00 -0700 Subject: [PATCH] docs for debug mode --- Makefile | 16 ++++++++-- docs/annotations/value_annotations.rst | 2 +- docs/api_reference.rst | 8 +++++ docs/index.rst | 2 +- docs/reference_implementations/debugging.rst | 29 +++++++++++++++++++ .../index.rst} | 6 ++++ 6 files changed, 58 insertions(+), 5 deletions(-) create mode 100644 docs/reference_implementations/debugging.rst rename docs/{reference_implementations.rst => reference_implementations/index.rst} (99%) diff --git a/Makefile b/Makefile index 1e1bd5f..d19a1a1 100644 --- a/Makefile +++ b/Makefile @@ -1,10 +1,16 @@ # Makefile for PyBryt -# to generate a release, use `make release` with the `VERSION` argument: +# ------------------- +# To generate a release, use `make release` with the `VERSION` argument: # $ make release VERSION=0.0.1 -# to run tests, use `make test` with the `TESTPATH` and/or `PYTESTOPTS` arguments: +# +# To run tests, use `make test` with the `TESTPATH` and/or `PYTESTOPTS` arguments: # $ make test -# the `testcov` target can be used to build a local copy of the code coverage in HTML +# +# The `testcov` target can be used to build a local copy of the code coverage in HTML: # $ make testcov +# +# To build the docs, use `make docs`: +# $ make docs PYTEST = pytest TESTPATH = tests @@ -29,3 +35,7 @@ testcov: covhtml: testcov $(COVERAGE) html + +.PHONY: docs +docs: + $(MAKE) -C docs html diff --git a/docs/annotations/value_annotations.rst b/docs/annotations/value_annotations.rst index 0cbbfd4..0535f81 100644 --- a/docs/annotations/value_annotations.rst +++ b/docs/annotations/value_annotations.rst @@ -105,7 +105,7 @@ equivalent may not be suitable to the problem at hand. For cases like this, you custom equivalence function that the value annotation will use instead to determine if two objects are equal. The equivalence function should return ``True`` if the objects are equal and ``False`` otherwise. If the equivalence function raises an error, this will be interpeted as -``False``. +``False`` (unless :ref:`debug mode` is enabled). For example, we could implement the ``string_capitalization`` invariant using a custom equivalence function: diff --git a/docs/api_reference.rst b/docs/api_reference.rst index ee58aa6..91d50b3 100644 --- a/docs/api_reference.rst +++ b/docs/api_reference.rst @@ -98,6 +98,14 @@ Reference Results .. autofunction:: pybryt.reference.generate_report +Debug mode +++++++++++ + +.. automodule:: pybryt.debug + :members: + :undoc-members: + + Student Implementations ----------------------- diff --git a/docs/index.rst b/docs/index.rst index 999680e..062b3f4 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -12,7 +12,7 @@ PyBryt Documentation getting_started annotations/index - reference_implementations + reference_implementations/index student_implementations cli_reference api_reference diff --git a/docs/reference_implementations/debugging.rst b/docs/reference_implementations/debugging.rst new file mode 100644 index 0000000..6687f09 --- /dev/null +++ b/docs/reference_implementations/debugging.rst @@ -0,0 +1,29 @@ +.. _debugging: + +Debugging References +==================== + +To assist in debugging your reference implementations, PyBryt comes with a debug mode that can be +enabled programmatically. To enable debug mode, use +:py:func:`pybryt.enable_debug_mode`. To disable debug mode, use +:py:func:`pybryt.disable_debug_mode`. Alternatively, you can +enable debug mode in a ``with`` block uses the context manager +:py:obj:`pybryt.debug_mode`. + +.. code-block:: python + + pybryt.enable_debug_mode() + # debug your reference + pybryt.disable_debug_mode() + + # or... + + with pybryt.debug_mode(): + # debug your reference + +In debug mode, PyBryt will raise exceptions instead of ignoring conditions that could cause +unexpected behavior. Currently, conditions that raise exceptions in debug mode are: + +* when a custom equivalence function is passed to a :py:class:`Value` + annotation along with ``atol`` and/or ``rtol`` +* when a custom equivalence function raises an exception diff --git a/docs/reference_implementations.rst b/docs/reference_implementations/index.rst similarity index 99% rename from docs/reference_implementations.rst rename to docs/reference_implementations/index.rst index 77955a6..a3adc20 100644 --- a/docs/reference_implementations.rst +++ b/docs/reference_implementations/index.rst @@ -1,6 +1,12 @@ Reference Implementations ========================= +.. toctree:: + :maxdepth: 3 + :hidden: + + debugging + The functional unit of PyBryt is a reference implementation. A **reference implenetation** is a set of conditions expected of students' code that determine whether a student has correctly implemented some program. They are constructed by creating a series of :ref:`annotations` that are