diff options
| -rw-r--r-- | CHANGES | 2 | ||||
| -rw-r--r-- | doc/config.rst | 10 | ||||
| -rw-r--r-- | doc/ext/doctest.rst | 3 | ||||
| -rw-r--r-- | sphinx/builders/html.py | 3 | ||||
| -rw-r--r-- | sphinx/config.py | 1 | ||||
| -rw-r--r-- | sphinx/highlighting.py | 13 | ||||
| -rw-r--r-- | sphinx/writers/latex.py | 4 | ||||
| -rw-r--r-- | tests/test_highlighting.py | 16 |
8 files changed, 43 insertions, 9 deletions
@@ -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 diff --git a/doc/config.rst b/doc/config.rst index 17e6b452..dc9fe096 100644 --- a/doc/config.rst +++ b/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 ------------------- diff --git a/doc/ext/doctest.rst b/doc/ext/doctest.rst index 6bd5efb6..1ef2e807 100644 --- a/doc/ext/doctest.rst +++ b/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. diff --git a/sphinx/builders/html.py b/sphinx/builders/html.py index 0fc652a0..5338c947 100644 --- a/sphinx/builders/html.py +++ b/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: diff --git a/sphinx/config.py b/sphinx/config.py index aa09bd2b..14708289 100644 --- a/sphinx/config.py +++ b/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'), diff --git a/sphinx/highlighting.py b/sphinx/highlighting.py index 5bd0fe00..aa1cbd18 100644 --- a/sphinx/highlighting.py +++ b/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)]) diff --git a/sphinx/writers/latex.py b/sphinx/writers/latex.py index 51e043c1..4d2e6169 100644 --- a/sphinx/writers/latex.py +++ b/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 = [] diff --git a/tests/test_highlighting.py b/tests/test_highlighting.py index ea1f25f1..7c303283 100644 --- a/tests/test_highlighting.py +++ b/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 |