[docs] [issue15629] Add to regrtest the ability to run Lib and Doc doctests
R. David Murray
report at bugs.python.org
Mon Sep 17 16:24:50 CEST 2012
R. David Murray added the comment:
I've given this some more thought, and I'm leaning toward Antoine's POV here.
The point of running the doctests in the docs is not to test python, but to test the docs. Sphinx has a facility to do that: make doctest. So I think it is better to use that doc-specific infrastructure to test the docs. This also allows us to use the full Sphinx facilities to work with those doctests, which includes hiding the not-necessary-for-docs bits.
I think we should be moving *away* from having special infrastructure in regrtest. As much stuff as makes sense should be moved to unittest, and we've been slowly doing that. Correspondingly, we should use Sphinx's native test facilities, not add special stuff to regrtest. If Sphinx doesn't have the ability to run individual files, we should add that ability to Sphinx, not regrtest. (Note: I personally do not use the ability recently added to regrtest to select unit tests from the command line, instead I use the unittest CLI directly, and I think that's the better way to do it. IMO regrtest should be focused on running the test *suite*, not on running individual tests.)
Once we've refined the docs so that 'make doctest' runs cleanly, we should automate the testing of the docs in some fashion. One way to do that would be to define a test module that handles the interfacing with Sphinx, and is controlled by a resource that is *not* included in -uall, and is then explicitly enabled on certain buildbots.
Doctests in module files could be handled the same way: build a test module that does whatever autodiscovery is needed, and control it via a resource not included in -uall. (I am, however, open to the argument that this one should be included in -uall.)
Again, there already exists a way to invoke individual files, using the native doctest facilities. So adding hooks to regrtest is not really needed, IMO. Also again, if the doctest CLI is lacking, the improvement should go into doctest.
Python tracker <report at bugs.python.org>
More information about the docs