Georg Brandl avatar Georg Brandl committed d91bf8e

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

Comments (0)

Files changed (8)

 * 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
 
    .. versionadded:: 0.5
 
-
 .. confval:: modindex_common_prefix
 
    A list of prefixes that are ignored for sorting the module index (e.g.,
 
    .. 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

    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

             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:
         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

 \newcommand\PYGZrb{]}
 '''
 
+doctestopt_re = re.compile(r'#\s*doctest:.+$', re.MULTILINE)
 
 parsing_exceptions = (SyntaxError, UnicodeEncodeError)
 if sys.version_info < (2, 5):
     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
                             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)}
             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
             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

         # 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

 
 class MyFormatter(HtmlFormatter):
     def format(self, tokensource, outfile):
-        outfile.write('test')
+        for tok in tokensource:
+            outfile.write(tok[1])
 
 
 class ComplainOnUnhighlighted(PygmentsBridge):
     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
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.