Convert logging usage doctests to testable snippets

[tseaver]

Toward #212 / #2535.

[dhermes]

@jonparrott Can you also peek at these?

[theacodes]

This looks okay to me as a start, but it is concerning to see so much setup/cleanup logic in the snippet function body. Pytest fixtures can help a lot with that, or just having separate test functions for each snippet. We do both in python-docs-samples.

[daspecster]

Fixture example from python-docs-samples.

@pytest.fixture
def example_log():
    client = logging.Client()
    logger = client.logger(TEST_LOGGER_NAME)
    text = 'Hello, world.'
    logger.log_text(text)
    return text

This looks pretty nice!
http://doc.pytest.org/en/latest/fixture.html

[dhermes]

@tseaver Here is a proof of concept for running readable interpreter snippets without worrying about calling eval / exec etc.

First, create a fake module (or any object really) with our content in the __doc__

>>> import types
>>> fake_mod = types.ModuleType('haha-nope')
>>> fake_mod.__doc__ = """\
... Here is some prose, and then a dragon appears
... and it makes sure division::
...
... >>> a = 45
... >>> a / 3
... 15
...
... and then the bunny hops down the lane and we
... find out we have to print a null::
...
... >>> b = {}
... >>> v = b.get('anything')
... >>> v
... >>> print(v)
... None
... """

then hand that object off to doctest.run_docstring_examples

>>> import doctest
>>> fake_globals = {}
>>> doctest.run_docstring_examples(fake_mod, fake_globals, verbose=False, name='foo')
>>> doctest.run_docstring_examples(fake_mod, fake_globals, verbose=True, name='foo')
Finding tests in foo
Trying:
    a = 45
Expecting nothing
ok
Trying:
    a / 3
Expecting:
    15
ok
Trying:
    b = {}
Expecting nothing
ok
Trying:
    v = b.get('anything')
Expecting nothing
ok
Trying:
    v
Expecting nothing
ok
Trying:
    print(v)
Expecting:
    None
ok