[Python-checkins] r66341 - in doctools/trunk: CHANGES doc/config.rst doc/markup/code.rst sphinx/config.py sphinx/highlighting.py sphinx/htmlwriter.py sphinx/latexwriter.py

Tue Sep 9 21:10:09 CEST 2008

Author: georg.brandl
Date: Tue Sep 9 21:10:09 2008
New Revision: 66341
Log:
Add default highlight language selection support.
Add support for recognizing Python 3 console output.
Modified:
 doctools/trunk/CHANGES
 doctools/trunk/doc/config.rst
 doctools/trunk/doc/markup/code.rst
 doctools/trunk/sphinx/config.py
 doctools/trunk/sphinx/highlighting.py
 doctools/trunk/sphinx/htmlwriter.py
 doctools/trunk/sphinx/latexwriter.py
Modified: doctools/trunk/CHANGES
==============================================================================

--- doctools/trunk/CHANGES	(original)
+++ doctools/trunk/CHANGES	Tue Sep 9 21:10:09 2008
@@ -27,6 +27,10 @@
 built documentation, and only written to stderr. If you want the
 old behavior, set the new config value ``keep_warnings`` to True.
 
+* The new config value ``highlight_language`` set a global default
+ for highlighting. When ``'python3'`` is selected, console output
+ blocks are recognized like for ``'python'``.
+
 * ``SerializingHTMLBuilder`` was added as new abstract builder that
 can be subclassed to serialize build HTML in a specific format.
 The ``PickleHTMLBuilder`` is a concrete subclass of it that uses
Modified: doctools/trunk/doc/config.rst
==============================================================================
--- doctools/trunk/doc/config.rst	(original)
+++ doctools/trunk/doc/config.rst	Tue Sep 9 21:10:09 2008
@@ -212,6 +212,14 @@
 %Y'`` (or, if translation is enabled with :confval:`language`, am equivalent
 %format for the selected locale).
 
+.. confval:: highlight_language
+
+ The default language to highlight source code in. The default is
+ ``'python'``. The value should be a valid Pygments lexer name, see
+ :ref:`code-examples` for more details.
+
+ .. versionadded:: 0.5
+ 
 .. confval:: pygments_style
 
 The style name to use for Pygments highlighting of source code. Default is
Modified: doctools/trunk/doc/markup/code.rst
==============================================================================
--- doctools/trunk/doc/markup/code.rst	(original)
+++ doctools/trunk/doc/markup/code.rst	Tue Sep 9 21:10:09 2008
@@ -1,5 +1,7 @@
 .. highlight:: rest
 
+.. _code-examples:
+
 Showing code examples
 ---------------------
 
@@ -23,7 +25,9 @@
 installed) and handled in a smart way:
 
 * There is a "highlighting language" for each source file. Per default, this is
- ``'python'`` as the majority of files will have to highlight Python snippets.
+ ``'python'`` as the majority of files will have to highlight Python snippets,
+ but the doc-wide default can be set with the :confval:`highlight_language`
+ config value.
 
 * Within Python highlighting mode, interactive sessions are recognized
 automatically and highlighted appropriately.
@@ -48,7 +52,7 @@
 * The valid values for the highlighting language are:
 
 * ``none`` (no highlighting)
- * ``python`` (the default)
+ * ``python`` (the default when :confval:`highlight_language` isn't set)
 * ``rest``
 * ``c``
 * ... and any other lexer name that Pygments supports.
Modified: doctools/trunk/sphinx/config.py
==============================================================================
--- doctools/trunk/sphinx/config.py	(original)
+++ doctools/trunk/sphinx/config.py	Tue Sep 9 21:10:09 2008
@@ -44,6 +44,7 @@
 add_module_names = (True, True),
 show_authors = (False, True),
 pygments_style = ('sphinx', False),
+ highlight_language = ('python', False),
 templates_path = ([], False),
 template_bridge = (None, False),
 keep_warnings = (False, True),
Modified: doctools/trunk/sphinx/highlighting.py
==============================================================================
--- doctools/trunk/sphinx/highlighting.py	(original)
+++ doctools/trunk/sphinx/highlighting.py	Tue Sep 9 21:10:09 2008
@@ -51,6 +51,9 @@
 none = TextLexer(),
 python = PythonLexer(),
 pycon = PythonConsoleLexer(),
+ # the python3 option exists as of Pygments 0.12, but it doesn't
+ # do any harm in previous versions
+ pycon3 = PythonConsoleLexer(python3=True),
 rest = RstLexer(),
 c = CLexer(),
 )
@@ -106,43 +109,54 @@
 return '\\begin{Verbatim}[commandchars=@\\[\\]]\n' + \
 source + '\\end{Verbatim}\n'
 
+ def try_parse(self, src):
+ # Make sure it ends in a newline
+ src += '\n'
+
+ # Replace "..." by a mark which is also a valid python expression
+ # (Note, the highlighter gets the original source, this is only done
+ # to allow "..." in code and still highlight it as Python code.)
+ mark = "__highlighting__ellipsis__"
+ src = src.replace("...", mark)
+
+ # lines beginning with "..." are probably placeholders for suite
+ src = re.sub(r"(?m)^(\s*)" + mark + "(.)", r"1円"+ mark + r"# 2円", src)
+
+ # if we're using 2.5, use the with statement
+ if sys.version_info >= (2, 5):
+ src = 'from __future__ import with_statement\n' + src
+
+ if isinstance(src, unicode):
+ # Non-ASCII chars will only occur in string literals
+ # and comments. If we wanted to give them to the parser
+ # correctly, we'd have to find out the correct source
+ # encoding. Since it may not even be given in a snippet,
+ # just replace all non-ASCII characters.
+ src = src.encode('ascii', 'replace')
+
+ try:
+ parser.suite(src)
+ except parsing_exceptions:
+ return False
+ else:
+ return True
+
 def highlight_block(self, source, lang, linenos=False):
 if not pygments:
 return self.unhighlighted(source)
- if lang == 'python':
+ if lang in ('py', 'python'):
 if source.startswith('>>>'):
 # interactive session
 lexer = lexers['pycon']
 else:
 # maybe Python -- try parsing it
- src = source + '\n'
-
- # Replace "..." by a mark which is also a valid python expression
- # (Note, the highlighter gets the original source, this is only done
- # to allow "..." in code and still highlight it as Python code.)
- mark = "__highlighting__ellipsis__"
- src = src.replace("...", mark)
-
- # lines beginning with "..." are probably placeholders for suite
- src = re.sub(r"(?m)^(\s*)" + mark + "(.)", r"1円"+ mark + r"# 2円", src)
-
- # if we're using 2.5, use the with statement
- if sys.version_info >= (2, 5):
- src = 'from __future__ import with_statement\n' + src
-
- if isinstance(src, unicode):
- # Non-ASCII chars will only occur in string literals
- # and comments. If we wanted to give them to the parser
- # correctly, we'd have to find out the correct source
- # encoding. Since it may not even be given in a snippet,
- # just replace all non-ASCII characters.
- src = src.encode('ascii', 'replace')
- try:
- parser.suite(src)
- except parsing_exceptions:
- return self.unhighlighted(source)
- else:
+ if self.try_parse(source):
 lexer = lexers['python']
+ else:
+ return self.unhighlighted(source)
+ elif lang in ('python3', 'py3') and source.startswith('>>>'):
+ # for py3, recognize interactive sessions, but do not try parsing...
+ lexer = lexers['pycon3']
 else:
 if lang in lexers:
 lexer = lexers[lang]
Modified: doctools/trunk/sphinx/htmlwriter.py
==============================================================================
--- doctools/trunk/sphinx/htmlwriter.py	(original)
+++ doctools/trunk/sphinx/htmlwriter.py	Tue Sep 9 21:10:09 2008
@@ -49,7 +49,7 @@
 self.highlighter = PygmentsBridge('html', builder.config.pygments_style)
 self.no_smarty = 0
 self.builder = builder
- self.highlightlang = 'python'
+ self.highlightlang = builder.config.highlight_language
 self.highlightlinenothreshold = sys.maxint
 self.protect_literal_text = 0
 
Modified: doctools/trunk/sphinx/latexwriter.py
==============================================================================
--- doctools/trunk/sphinx/latexwriter.py	(original)
+++ doctools/trunk/sphinx/latexwriter.py	Tue Sep 9 21:10:09 2008
@@ -157,7 +157,7 @@
 self.bibitems = []
 self.table = None
 self.next_table_colspec = None
- self.highlightlang = 'python'
+ self.highlightlang = builder.config.highlight_language
 self.highlightlinenothreshold = sys.maxint
 self.written_ids = set()
 if docclass == 'manual':
