Clean up and doc the test.runWith*() functions

[ceball]

def run(notebook, rules=None, filename=None):
    nb = nbformat.read(notebook, 4)
    name = filename or notebook[:-6] + '_test.py'  # remove .ipynb, replace with _test.py
    [... generate test file...]
    return name

def runWithReturn(notebook, executable=None, rules=None):
    name = run([...])
    executable = executable or [sys.executable, '-m', 'pytest', '-v']
    argv = executable + [name]
    return subprocess.check_output(argv)

def runWithReport(notebook, executable=None, rules=None, collect_only=False):
    tmpd = tempfile.mkdtemp()
    py_file = os.path.join(tmpd, os.path.basename(notebook).replace('.ipynb', '.py'))
    json_file = os.path.join(tmpd, os.path.basename(notebook).replace('.ipynb', '.json'))
    _ = run(notebook, filename=py_file, rules=rules)
    ret = []
    [...run with ?coverage and collect results - TODO: read this code and see...]
    return ret

def runWithHTMLReturn(notebook, executable=None, rules=None):
    '''use pytest self contained html'''
    name = run(notebook, rules=rules)
    html = name.replace('.py', '.html')
    executable = executable or [sys.executable, '-m', 'pytest', '-v']
    argv = executable + ['--html=' + html, '--self-contained-html', name]
    subprocess.call(argv)
    with open(html, 'r', encoding='utf-8') as fp:
        return fp.read()

def runWithHTMLReturn2(notebook, executable=None, rules=None):
    '''use custom return objects'''
    ret = ''
    executable = executable or [sys.executable, '-m', 'pytest', '-v']
    ret_tmp = run(notebook, rules=rules)
    for test in ret_tmp:
        test = test.to_html()
        ret += '<p>' + test + '</p>'
    return '<div style="display: flex; flex-direction: column;">' + test + '</div>'

[ceball]

Notes:

• runWithHTMLReturn() works fine.
• runWithHTMLReturn2() does nothing (doesn't actually run any tests - bug). Is it used? Seems not.
• runWithReport() not quite working (see test.runWithReport() fails immediately on first error rather than reporting failures #126) and still undocumented.
• runWithReturn() works fine.
• run() does no running :) Should be generate_test_script() or something like that.

python -m nbcelltests.test ... does not actually use any of the run functions, but most likely should.