doc update

Author: machow

docs/source/Home.md

@@ -34,7 +34,10 @@ Overview
 
 To get started, make sure to check out the [Quickstart Guide](quickstart_guide.md).
 
-To robustly test the equality of objects, and results of evaluations, it has to fetch the information from the respective processes, i.e. the student and solution processes. By default, this is done through a process of 'dilling' and 'undilling', but it's also possible to define your own converters to customize the way objects and results are compared. For more background on this, check out the [Processes article](expression_tests.md). For some more background on the principle of 'sub-SCTs', i.e. sets of tests to be called on a particular part or a particular state of a student's submission, have a look at the [Part Checks article](part_checks.rst).
+```eval_rst
+
+To robustly test the equality of objects, and results of evaluations, it has to fetch the information from the respective processes, i.e. the student and solution processes. By default, this is done through a process of 'dilling' and 'undilling', but it's also possible to define your own converters to customize the way objects and results are compared. For more background on this, check out :ref:`managing-processes`. For some more background on the principle of 'sub-SCTs', i.e. sets of tests to be called on a particular part or a particular state of a student's submission, have a look at the :doc:`Part Checks article <part_checks>`.
+```
 
 The remainder of the wiki goes over every test function that `pythonwhat` features, explaining all arguments and covering different use cases. They will give you an idea of how, why and when to use them.
 

docs/source/expression_tests.md

@@ -320,6 +320,10 @@ For example, the SCT below shows how to run some `pre_code`, and then evaluate t
 Ex().check_function_def('my_fun').call("f(1, 2)", test="output", pre_code="x = 1")
 ```
 
+```eval_rst
+.. _managing-processes:
+```
+
 
 Managing Processes
 -----------------

docs/source/part_checks.rst

@@ -161,8 +161,7 @@ Helper Functions
 multi
 ~~~~~~~
 
-Runs multiple subtests. 
-
+.. autofunction:: pythonwhat.check_funcs.multi
 
 Comma separated arguments
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -214,6 +213,8 @@ followed by its iterator.
 set_context
 ~~~~~~~~~~~~~
 
+.. autofunction:: pythonwhat.check_funcs.set_context
+
 Sets the value of a temporary variable, such as ``ii`` in the list comprehension below.
 
 .. code::
@@ -261,6 +262,8 @@ When you try to set context values that don't match any target variables in the
 with_context
 ~~~~~~~~~~~~~~
 
+.. autofunction:: pythonwhat.check_funcs.with_context
+
 Runs subtests after setting the context for a ``with`` statement.
 
 This function takes arguments in the same form as ``multi``. 
@@ -291,6 +294,8 @@ and replacing step (3) with any sub-tests given as arguments.
 fail
 ~~~~~~
 
+.. autofunction:: pythonwhat.check_funcs.fail
+
 Fails. This function takes a single argument, ``msg``, that is the feedback given to the student.
 Note that this would be a terrible idea for grading submissions, but may be useful while writing SCTs.
 For example, failing a test will highlight the code as if the previous test/check had failed.
@@ -315,14 +320,14 @@ Check Functions
   (e.g. ``Ex().check_list_comp(0).check_ifs(0)``)
 * **missing_msg**: optional feedback message if node or part doesn't exist.
 
-
 Note that code in all caps indicates the name of a piece of code that may be inspected using, ``check_{part}``, 
 where ``{part}`` is replaced by the name in caps (e.g. ``check_if_else(0).check_test()``).
 Target variables are those that may be set using ``set_context``.
 These variables may only be set in places where python would set them.
 For example, this means that a list comprehension's ITER part has no target variables,
 but its BODY does.
 
+
 +------------------------+------------------------------------------------------+-------------------+
 | check                  | parts                                                | target variables  |
 +========================+======================================================+===================+
@@ -380,9 +385,9 @@ but its BODY does.
 |                        |        FINALBODY                                     |                   |
 |                        |                                                      |                   |
 +------------------------+------------------------------------------------------+-------------------+
-|check_with(0)           |   .. code:: python                                   | `f``              |
+|check_with(0)           |   .. code:: python                                   | ``f``             |
 |                        |                                                      |                   |
-|                        |     with CONTEXT_TEST as f:                          |                   |
+|                        |     with CONTEXT[0] as f1, CONTEXT[1] as f2:         |                   |
 |                        |         BODY                                         |                   |
 |                        |                                                      |                   |
 +------------------------+------------------------------------------------------+-------------------+

docs/source/simple_tests/has_equal_ast.md

@@ -2,8 +2,7 @@ has_equal_ast
 --------------
 
 ```eval_rst
-.. automodule:: pythonwhat.check_funcs.has_equal_ast
-    :members:
+.. autofunction:: pythonwhat.check_funcs.has_equal_ast
 ```
 
 An abstract syntax tree (AST) is a way of representing the high-level structure of python code.

pythonwhat/check_funcs.py

@@ -402,6 +402,11 @@ def call(args,
 from pythonwhat import utils
 
 def has_equal_ast(incorrect_msg="FMT: Your code does not seem to match the solution.", state=None):
+    """Test whether abstract syntax trees match between the student and solution code.
+
+    Args:
+        incorrect_msg: message displayed when ASTs mismatch.
+    """
     rep = Reporter.active_reporter
 
     stu_rep = ast.dump(state.student_tree)
@@ -424,6 +429,34 @@ def has_expr(incorrect_msg="FMT:Unexpected expression {test}: expected `{sol_eva
              highlight=None,
              state=None,
              test=None):
+    """Run student and solution code, compare returned value, printed output, or errors.
+
+    Args:
+        incorrect_msg (str): feedback message if the output of the expression in the solution doesn't match
+          the one of the student. This feedback message will be expanded if it is used in the context of
+          another test function, like test_if_else.
+        error_msg (str): feedback message if there was an error when running the student code.
+          Note that when testing for an error, this message is displayed when none is raised.
+        undefined_msg (str): feedback message if the name argument is defined, but a variable 
+          with that name doesn't exist after running the student code.
+        extra_env (dict): set variables to the extra environment. They will update the student
+          and solution environment in the active state before the student/solution code in the active
+          state is ran. This argument should contain a dictionary with the keys the names of
+          the variables you want to set, and the values are the values of these variables.
+        context_vals (list): set variables which are bound in a for loop to certain values. This argument is
+          only useful if you use the function in a test_for_loop. It contains a list with the values
+          of the bound variables.
+        expr_code (str): if this variable is not None, the expression in the student/solution code will not
+          be ran. Instead, the given piece of code will be ran in the student as well as the solution environment
+          and the result will be compared.
+        pre_code (str): the code in string form that should be executed before the expression is executed.
+          This is the ideal place to set a random seed, for example.
+        keep_obj_in_env (list()): a list of variable names that should be hold in the copied environment where
+          the expression is evaluated. All primitive types are copied automatically, other objects have to
+          be passed explicitely.
+        name (str): the name of a variable, or expression, whose value will be tested after running the
+          student and solution code. This could be thought of as post code.
+    """
     rep = Reporter.active_reporter
 
     # run function to highlight a block of code