> I just had a problem with doctests. It manifested as an
> error that occurred when I did
> >>> import StringIO in my doctest.

Maybe you are running the doctest with Python 3. The StringIO module is no more available in Python 3, so your doctest will fail on Python 3 and will pass on Python 2.

> 1. There is no example of a multiple-line doctest fixture:
> specifically, a fixture which involves at least one line to
> set up state, and another line to be the example that tested.
> I suggest adding such an example as a new section, "26.3.2.
> Usage: multi-line tests".
> Note that the example in 26.3.3.2 doesn't count: that is a
> Compound Statement, and I'm talking about a test consisting
> of multiple interactive statements.

The example in section 26.3.3.2 [1], before the compound statement (the if/else), contains two simple statements. I also think the example is complete and straightforward for its purpose, and it does not have to be complicated adding avanced features. If you want a more complex control over your tests, for instance adding fixtures, you can find how to do it later, in [2].

> 2. Section "26.3.3.2. How are Docstring Examples Recognized?" does
> not talk about when to use a PS1 prefix (>>>) and when to use a
> PS2 prefix (...). It should say to use the PS1 at the start of each
> Python "interactive statement", that is, a statement list ending with
> a newline, or a Compound Statement. And, to use the PS2 to prefix each
> continuing line within a Compound Statement. 

I am -1 on this. IMHO there is no need to add extra description to a such self-explaining, clear and concise example. But this I think is also clear from the beginning. Infact, the first line of the doc says: "The doctest module searches for pieces of text that look like interactive Python sessions"

> 3. Section "26.3.3.3. What’s the Execution Context?" is not
> clear about the crucial difference between state that accumulates
> within a single docstring from Example to Example, and that is reset
> from one docstring to another. The phrase "so that one test in M can’t
> leave behind crumbs that accidentally allow another test to work"
> can be interpreted as applying within a single docstring. The phrase
> "names defined earlier in the docstring being run" is easy to miss.

Also this section IMO is well written and clear. I do not know what to say... If someone else thinks it is not enough understandable, maybe the better think to do is to add a very small example, with two functions, that shows their docstrings have independent globals.

> Unless someone tells me otherwise, I'll get around to filing similar
> issues against Python 3.6 and Python 2.7.
> Then it's my intention to write improvements to the documentation
> for Python 3.7, 3.6, and 2.7, and submit each of those.

Keep in mind that writing a patch is not enough. The patch has to be reviewed, and that means other people have to find the time to work on it. I suggest you to watch this talk of Raymond Hettinger, before going on:

https://www.youtube.com/watch?v=voXVTjwnn-U


[1] https://docs.python.org/3/library/doctest.html#how-are-docstring-examples-recognized
[2] https://docs.python.org/3/library/doctest.html#unittest-api