#169: Added the `trim_doctest_flags` config value, which is true by default.

CHANGES

@@ -18,6 +18,8 @@ Release 1.0 (in development)
 * Added the ``latex_docclass`` config value and made the "twoside"
   documentclass option overridable by "oneside".
 
+* Added the ``trim_doctest_flags`` config value, which is true by default.
+
 * Added the ``extlinks`` extension.
 
 * Allow searching for object names including the module name, like

doc/config.rst

@@ -185,7 +185,6 @@ General configuration
 
    .. versionadded:: 0.5
 
-
 .. confval:: modindex_common_prefix
 
    A list of prefixes that are ignored for sorting the module index (e.g.,
@@ -195,6 +194,15 @@ General configuration
 
    .. versionadded:: 0.6
 
+.. confval:: trim_doctest_flags
+
+   If true, doctest flags (comments looking like ``# doctest: FLAG, ...``) at
+   the ends of lines are removed for all code blocks showing interactive Python
+   sessions (i.e. doctests).  Default is true.  See the extension
+   :mod:`~sphinx.ext.doctest` for more possibilities of including doctests.
+
+   .. versionadded:: 1.0
+
 
 Project information
 -------------------

doc/ext/doctest.rst

@@ -196,4 +196,5 @@ There are also these config values for customizing the doctest extension:
    Note though that you can't have blank lines in reST doctest blocks.  They
    will be interpreted as one block ending and another one starting.  Also,
    removal of ``<BLANKLINE>`` and ``# doctest:`` options only works in
-   :dir:`doctest` blocks.
+   :dir:`doctest` blocks, though you may set :confval:`trim_doctest_flags` to
+   achieve the latter in all code blocks with Python console content.

sphinx/builders/html.py

@@ -115,7 +115,8 @@ class StandaloneHTMLBuilder(Builder):
             style = self.theme.get_confstr('theme', 'pygments_style', 'none')
         else:
             style = 'sphinx'
-        self.highlighter = PygmentsBridge('html', style)
+        self.highlighter = PygmentsBridge('html', style,
+                                          self.config.trim_doctest_flags)
 
     def init_translator_class(self):
         if self.config.html_translator_class:

sphinx/config.py

@@ -54,6 +54,7 @@ class Config(object):
         keep_warnings = (False, 'env'),
         modindex_common_prefix = ([], 'html'),
         rst_epilog = (None, 'env'),
+        trim_doctest_flags = (True, 'env'),
 
         # HTML options
         html_theme = ('default', 'html'),

sphinx/highlighting.py

@@ -78,6 +78,7 @@ _LATEX_STYLES = r'''
 \newcommand\PYGZrb{]}
 '''
 
+doctestopt_re = re.compile(r'#\s*doctest:.+$', re.MULTILINE)
 
 parsing_exceptions = (SyntaxError, UnicodeEncodeError)
 if sys.version_info < (2, 5):
@@ -92,7 +93,8 @@ class PygmentsBridge(object):
     html_formatter = HtmlFormatter
     latex_formatter = LatexFormatter
 
-    def __init__(self, dest='html', stylename='sphinx'):
+    def __init__(self, dest='html', stylename='sphinx',
+                 trim_doctest_flags=False):
         self.dest = dest
         if not pygments:
             return
@@ -106,6 +108,7 @@ class PygmentsBridge(object):
                             stylename)
         else:
             style = get_style_by_name(stylename)
+        self.trim_doctest_flags = trim_doctest_flags
         if dest == 'html':
             self.fmter = {False: self.html_formatter(style=style),
                           True: self.html_formatter(style=style, linenos=True)}
@@ -167,6 +170,8 @@ class PygmentsBridge(object):
             source = source.decode()
         if not pygments:
             return self.unhighlighted(source)
+
+        # find out which lexer to use
         if lang in ('py', 'python'):
             if source.startswith('>>>'):
                 # interactive session
@@ -191,6 +196,12 @@ class PygmentsBridge(object):
             else:
                 lexer = lexers[lang] = get_lexer_by_name(lang)
                 lexer.add_filter('raiseonerror')
+
+        # trim doctest options if wanted
+        if isinstance(lexer, PythonConsoleLexer) and self.trim_doctest_flags:
+            source = doctestopt_re.sub('', source)
+
+        # highlight via Pygments
         try:
             if self.dest == 'html':
                 return highlight(source, lexer, self.fmter[bool(linenos)])

sphinx/writers/latex.py

@@ -215,8 +215,8 @@ class LaTeXTranslator(nodes.NodeVisitor):
         # allow the user to override them all
         self.elements.update(builder.config.latex_elements)
 
-        self.highlighter = highlighting.PygmentsBridge(
-            'latex', builder.config.pygments_style)
+        self.highlighter = highlighting.PygmentsBridge('latex',
+            builder.config.pygments_style, builder.config.trim_doctest_flags)
         self.context = []
         self.descstack = []
         self.bibitems = []

tests/test_highlighting.py

@@ -37,7 +37,8 @@ class MyLexer(RegexLexer):
 
 class MyFormatter(HtmlFormatter):
     def format(self, tokensource, outfile):
-        outfile.write('test')
+        for tok in tokensource:
+            outfile.write(tok[1])
 
 
 class ComplainOnUnhighlighted(PygmentsBridge):
@@ -69,7 +70,16 @@ def test_set_formatter():
     PygmentsBridge.html_formatter = MyFormatter
     try:
         bridge = PygmentsBridge('html')
-        ret = bridge.highlight_block('foo', 'python')
-        assert ret == 'test'
+        ret = bridge.highlight_block('foo\n', 'python')
+        assert ret == 'foo\n'
+    finally:
+        PygmentsBridge.html_formatter = HtmlFormatter
+
+def test_trim_doctest_flags():
+    PygmentsBridge.html_formatter = MyFormatter
+    try:
+        bridge = PygmentsBridge('html', trim_doctest_flags=True)
+        ret = bridge.highlight_block('>>> 1+2 # doctest: SKIP\n3\n', 'pycon')
+        assert ret == '>>> 1+2 \n3\n'
     finally:
         PygmentsBridge.html_formatter = HtmlFormatter