user: Hi guys, welcome to introduction to DocTesting.

The kata is composed of two parts; in part (1) we write three small functions, and in part (2) we write a few doc tests for those functions.

Lets talk about the functions first...

    The reverse_list function takes a list and returns the reverse of it.
    If given an empty list, simply return an empty list.

The second function...

    The sum_list function takes a list as input and adds up all the values, 
    returning an integer. If the list is empty, return 0.

The third function...

    The head_of_list function simply returns the first item in the list.
    If the list is empty return None.

Each of these functions can be easily written with a single line of code; there are some tests for correctness but no tests for effciency.

Once you have implemented all three of these functions you can move onto phase two, which is writing doc tests. If you haven't written doc tests before then I suggest you check out the following documentation: 
https://docs.python.org/3/library/doctest.html

To complete this kata all you have to do is write **EXACTLY TWO** doc tests for each of the three functions (any more/less than that and you will fail the tests).

Here is an example:

    def double(y):
      """Function returns y * 2
      >>> double(2)
      4
      """
      return y * 2

In the example above we have a function called 'double' and a single doctest. When we run the doctest module Python will check if double(2) equals 4. If it does not, then the doctest module will flag up an error.

Please note that this is intended as a beginners introduction to docstrings, if you try to do something clever (such as writing doc tests to catch exceptions, or tinkering with the 'option flags'), you will probably fail a test or two. This is due to how the tests are written.  

Oh and one last thing, don't try and get too 'cheeky' and try something like:
    
    """
    >>> True
    True
    """

such a solution is (a) not in the spirit of things and (b) I got tests for that! :p

Good Luck!

~~~~~~~~~~~~~~~ Issues & Helpful hints ~~~~~~~~~~~~~~~~~~~~~~~

1) In addition to the 'don't get too clever rule', please try to be precise when making your doctests; [1,2] may fail where [1, 2] may succeed. Likewise, ">>>function(x)" may fail where ">>> function(x)" is likely to suceed *(note the difference is single " " character)*. In short, if you fail a test the first thing to check is that you dont have any unecessary characters/spaces and/or odd formating.

2) As you shall see from the kata discussion testing for None is tricky and lots of people are struggling to get None tests working. So I'm going to quickly show you a way to test for not that will (should) pass the kata:
  
    def is_string(string):
        """
        returns the string if the string is Not empty, otherwise returns None
        >>> is_string("") is None
        True
        """
        return string if string else None

3) If you happen to be struggling to actually complete the three functions in the first place then I would recomend you google *"Python Indexing", "Pythons sum function" and "if/else statements in Python"*.

Answer: {"fn_name": "reverse_list", "inputs": [[[1, 2, 3]], [[]]], "outputs": [[[3, 2, 1]], [[]]]}