Issue #12947: revert earlier workaround and use a monkey-patch to enable showing doctest directives only in the doctest docs.

This commit is contained in:
Georg Brandl 2012-10-10 16:45:11 +02:00
parent d469c400ed
commit 7495456ffc
2 changed files with 37 additions and 23 deletions

View File

@ -1,3 +1,5 @@
:keepdoctest:
:mod:`doctest` --- Test interactive Python examples
===================================================
@ -714,43 +716,28 @@ above.
An example's doctest directives modify doctest's behavior for that single
example. Use ``+`` to enable the named behavior, or ``-`` to disable it.
.. note::
Due to an `unfortunate limitation`_ of our current documentation
publishing process, syntax highlighting has been disabled in the examples
below in order to ensure the doctest directives are correctly displayed.
For example, this test passes::
.. _unfortunate limitation: http://bugs.python.org/issue12947
For example, this test passes:
.. code-block:: text
>>> print range(20) #doctest: +NORMALIZE_WHITESPACE
>>> print range(20) # doctest: +NORMALIZE_WHITESPACE
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9,
10, 11, 12, 13, 14, 15, 16, 17, 18, 19]
Without the directive it would fail, both because the actual output doesn't have
two blanks before the single-digit list elements, and because the actual output
is on a single line. This test also passes, and also requires a directive to do
so:
.. code-block:: text
so::
>>> print range(20) # doctest: +ELLIPSIS
[0, 1, ..., 18, 19]
Multiple directives can be used on a single physical line, separated by
commas:
.. code-block:: text
commas::
>>> print range(20) # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
[0, 1, ..., 18, 19]
If multiple directive comments are used for a single example, then they are
combined:
.. code-block:: text
combined::
>>> print range(20) # doctest: +ELLIPSIS
... # doctest: +NORMALIZE_WHITESPACE
@ -758,9 +745,7 @@ combined:
As the previous example shows, you can add ``...`` lines to your example
containing only directives. This can be useful when an example is too long for
a directive to comfortably fit on the same line:
.. code-block:: text
a directive to comfortably fit on the same line::
>>> print range(5) + range(10,20) + range(30,40) + range(50,60)
... # doctest: +ELLIPSIS

View File

@ -33,9 +33,38 @@ def new_visit_versionmodified(self, node):
self.body.append('<span class="versionmodified">%s</span>' % text)
from sphinx.writers.html import HTMLTranslator
from sphinx.writers.latex import LaTeXTranslator
from sphinx.locale import versionlabels
HTMLTranslator.visit_versionmodified = new_visit_versionmodified
HTMLTranslator.visit_versionmodified = new_visit_versionmodified
# monkey-patch HTML and LaTeX translators to keep doctest blocks in the
# doctest docs themselves
orig_visit_literal_block = HTMLTranslator.visit_literal_block
def new_visit_literal_block(self, node):
meta = self.builder.env.metadata[self.builder.current_docname]
old_trim_doctest_flags = self.highlighter.trim_doctest_flags
if 'keepdoctest' in meta:
self.highlighter.trim_doctest_flags = False
try:
orig_visit_literal_block(self, node)
finally:
self.highlighter.trim_doctest_flags = old_trim_doctest_flags
HTMLTranslator.visit_literal_block = new_visit_literal_block
orig_depart_literal_block = LaTeXTranslator.depart_literal_block
def new_depart_literal_block(self, node):
meta = self.builder.env.metadata[self.curfilestack[-1]]
old_trim_doctest_flags = self.highlighter.trim_doctest_flags
if 'keepdoctest' in meta:
self.highlighter.trim_doctest_flags = False
try:
orig_depart_literal_block(self, node)
finally:
self.highlighter.trim_doctest_flags = old_trim_doctest_flags
LaTeXTranslator.depart_literal_block = new_depart_literal_block
# Support for marking up and linking to bugs.python.org issues