Use manuel to run doctest files. #27
Conversation
We can't use the codeblock plugin for the using-logging test, instead resorting to manually execing the captured source. This is because stdout is not captured by a codeblock, so logging would be configured to go to the *real* stdout, not one captured by the next doctest we do (where we do want to use the doctest syntax) and our output wouldn't get seen. This was maddening to figure out. You can't use the capture plugin to capture literal includes, so we still have the chdir hacks. Overall it's not a whole lot of a win, at least right now. I changed some of the text strings that we log to make them a bit more descriptive. This was part of debuging too, but I think they're better. I ran into a problem doing 'python -m ZConfig.tests.test_readme' that I added a workaround for.
|
On Thu, Mar 16, 2017 at 2:57 PM, Jason Madden ***@***.***> wrote:
We can't use the codeblock plugin for the using-logging test, instead
resorting to manually execing the captured source. This is because
stdout is not captured by a codeblock, so logging would be configured
to go to the *real* stdout, not one captured by the next doctest we
do (where we do want to use the doctest syntax) and our output
wouldn't get seen. This was maddening to figure out.
You can't use the capture plugin to capture literal includes, so we
still have the chdir hacks.
Overall it's not a whole lot of a win, at least right now.
All that manual.capture gives you is access to example text. It doesn't run
anything. You then need to test that executing the text or comparing it to
output is as expected.
In the buildout docs, I ran examples in subprocesses (multi-processing
Process) and redirected output (assigned stdout and stderr) to a file. I
then compared actual and expected in doctests that were hidden behind ReST
comments, do they didn't clutter the documentation.
|
| @@ -7,26 +7,33 @@ framework. ZConfig provides one simple convenience function to do this: | |||
|
|
|||
| .. autofunction:: ZConfig.configureLoggers | |||
|
|
|||
|
|
|||
| Suppose we have the following logging configuration in a file called ``simple-root-config.conf``: | |||
|
|
|||
| .. literalinclude:: simple-root-config.conf | |||
There was a problem hiding this comment.
That seems like a reasonable approach too.
I wasn't aware of this. I assume this shows up on RTD.
Cool.
There was a problem hiding this comment.
Yeah, things look good on RTD, even before this: http://zconfig.readthedocs.io/en/latest/using-logging.html
The doctest examples were small enough that the prompts weren't much of an eyesore, at least not to me.
|
I agree that after using literalinclude the incremental benefit of manuel was small. |
I was expecting that from previous examples. It's not ideal---being able to use the codeblock plugin would be ideal---but it works and it's slightly cleaner to read, and really, just slightly cleaner to write, too because the execution is explicit instead of implicit.
Small but non-zero. It was nice to be able to use the same There are some other cleanups in here too, but I admit they're pretty unrelated to manuel proper. |
|
LGTM |
|
Thanks for the review! |
We can't use the codeblock plugin for the using-logging test, instead
resorting to manually execing the captured source. This is because
stdout is not captured by a codeblock, so logging would be configured
to go to the real stdout, not one captured by the next doctest we
do (where we do want to use the doctest syntax) and our output
wouldn't get seen. This was maddening to figure out.
You can't use the capture plugin to capture literal includes, so we
still have the chdir hacks.
Overall it's not a whole lot of a win, at least right now.
I changed some of the text strings that we log to make them a bit more
descriptive. This was part of debuging too, but I think they're
better.
I ran into a problem doing 'python -m ZConfig.tests.test_readme' that
I added a workaround for.