docs for debug mode

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

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<debugging>` is enabled).
 
 For example, we could implement the ``string_capitalization`` invariant using a custom
 equivalence function:

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
 -----------------------
 

docs/index.rst

@@ -12,7 +12,7 @@ PyBryt Documentation
 
    getting_started
    annotations/index
-   reference_implementations
+   reference_implementations/index
    student_implementations
    cli_reference
    api_reference

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<pybryt.debug.enable_debug_mode>`. To disable debug mode, use
+:py:func:`pybryt.disable_debug_mode<pybryt.debug.disable_debug_mode>`. Alternatively, you can 
+enable debug mode in a ``with`` block uses the context manager 
+:py:obj:`pybryt.debug_mode<pybryt.debug.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<pybryt.annotations.value.Value>`
+  annotation along with ``atol`` and/or ``rtol``
+* when a custom equivalence function raises an exception

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<annotations>` that are