From 3a2e101be564ffcb73dac708533d9178d90c2da8 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Wed, 10 Oct 2012 16:45:11 +0200 Subject: [PATCH 1/2] Issue #12947: revert earlier workaround and use a monkey-patch to enable showing doctest directives only in the doctest docs. --- Doc/library/doctest.rst | 7 +++++-- Doc/tools/sphinxext/pyspecific.py | 29 +++++++++++++++++++++++++++++ 2 files changed, 34 insertions(+), 2 deletions(-) diff --git a/Doc/library/doctest.rst b/Doc/library/doctest.rst index ed53f060517..ec8edbe0ac3 100644 --- a/Doc/library/doctest.rst +++ b/Doc/library/doctest.rst @@ -1,3 +1,5 @@ +:keepdoctest: + :mod:`doctest` --- Test interactive Python examples =================================================== @@ -652,7 +654,7 @@ example. Use ``+`` to enable the named behavior, or ``-`` to disable it. For example, this test passes:: - >>> print(list(range(20))) #doctest: +NORMALIZE_WHITESPACE + >>> print(list(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] @@ -664,7 +666,8 @@ so:: >>> print(list(range(20))) # doctest: +ELLIPSIS [0, 1, ..., 18, 19] -Multiple directives can be used on a single physical line, separated by commas:: +Multiple directives can be used on a single physical line, separated by +commas:: >>> print(list(range(20))) # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE [0, 1, ..., 18, 19] diff --git a/Doc/tools/sphinxext/pyspecific.py b/Doc/tools/sphinxext/pyspecific.py index 89bb86fc22c..9b2cc47c88f 100644 --- a/Doc/tools/sphinxext/pyspecific.py +++ b/Doc/tools/sphinxext/pyspecific.py @@ -33,9 +33,38 @@ def new_visit_versionmodified(self, node): self.body.append('%s ' % 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 From 83e51f48a8f8d2671caa99206e77752eb6c42a4d Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Wed, 10 Oct 2012 16:45:11 +0200 Subject: [PATCH 2/2] Issue #12947: revert earlier workaround and use a monkey-patch to enable showing doctest directives only in the doctest docs. --- Doc/library/doctest.rst | 31 ++++++++----------------------- Doc/tools/sphinxext/pyspecific.py | 29 +++++++++++++++++++++++++++++ 2 files changed, 37 insertions(+), 23 deletions(-) diff --git a/Doc/library/doctest.rst b/Doc/library/doctest.rst index 40cc73712cd..802113b7a15 100644 --- a/Doc/library/doctest.rst +++ b/Doc/library/doctest.rst @@ -1,3 +1,5 @@ +:keepdoctest: + :mod:`doctest` --- Test interactive Python examples =================================================== @@ -674,43 +676,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(list(range(20))) #doctest: +NORMALIZE_WHITESPACE + >>> print(list(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(list(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(list(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(list(range(20))) # doctest: +ELLIPSIS ... # doctest: +NORMALIZE_WHITESPACE @@ -718,9 +705,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(list(range(5)) + list(range(10, 20)) + list(range(30, 40))) ... # doctest: +ELLIPSIS diff --git a/Doc/tools/sphinxext/pyspecific.py b/Doc/tools/sphinxext/pyspecific.py index d4f17d8fc3e..e8eb70368a3 100644 --- a/Doc/tools/sphinxext/pyspecific.py +++ b/Doc/tools/sphinxext/pyspecific.py @@ -33,9 +33,38 @@ def new_visit_versionmodified(self, node): self.body.append('%s ' % 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