To answer the parenthetical question (I haven't looked at the doc issue itself), we don't doctest the examples because most of them were written before sphinx grew a doctest extension, so a lot of them don't pass for reasons that have nothing to do with code validity.  Issues and patches for making the doctests pass are welcome, and we have applied a number of them.  There is a lot of work to do before we could add running doctest to our doc buildbot, though.