Add highlight_options configuration value

This changeset adds the `highlight_options` configuration value, which
specifies a dict of key-value pairs to pass to the Pygments highlighter
specified with `highlight_language`. For example, specifying
`highlight_options = {'funcnamehighlighting' : False}` for the 'php'
lexer will disable function name highlighting.
Both the HTML and LaTeX writers have been updated to include the
options when calling `highlight_block()`, as long as the currently
selected language matches what was set with `highlight_language`, i.e.
not when modified by `highlight::` or `code-block::` directives.

CHANGES

@@ -9,6 +9,8 @@ Incompatible changes
 Features added
 --------------
 
+* Added ``highlight_options`` configuration value.
+
 Bugs fixed
 ----------
 

doc/config.rst

@@ -303,9 +303,17 @@ Project information
 
    .. versionadded:: 0.5
 
+.. confval:: highlight_options
+
+   A dictionary of options that modify the behavior of the lexer for the
+   selected language. These are lexer-specific. For the options understood by
+   each, see the `Pygments documentation <http://pygments.org/docs/lexers/>`_.
+
+   .. versionadded:: 1.3
+
 .. confval:: pygments_style
 
-   The style name to use for Pygments highlighting of source code.  The default
+   The style name to use for Pygments highlighting of source code.  The given
    style is selected by the theme for HTML output, and ``'sphinx'`` otherwise.
 
    .. versionchanged:: 0.3

sphinx/config.py

@@ -61,6 +61,7 @@ class Config(object):
         show_authors = (False, 'env'),
         pygments_style = (None, 'html'),
         highlight_language = ('python', 'env'),
+        highlight_options = ({}, 'env'),
         templates_path = ([], 'html'),
         template_bridge = (None, 'html'),
         keep_warnings = (False, 'env'),

sphinx/highlighting.py

@@ -134,7 +134,7 @@ class PygmentsBridge(object):
         else:
             return True
 
-    def highlight_block(self, source, lang, warn=None, force=False, **kwargs):
+    def highlight_block(self, source, lang, opts=None, warn=None, force=False, **kwargs):
         if not isinstance(source, text_type):
             source = source.decode()
 
@@ -164,7 +164,7 @@ class PygmentsBridge(object):
                 lexer = lexers[lang]
             else:
                 try:
-                    lexer = lexers[lang] = get_lexer_by_name(lang)
+                    lexer = lexers[lang] = get_lexer_by_name(lang, **opts)
                 except ClassNotFound:
                     if warn:
                         warn('Pygments lexer name %r is not known' % lang)

sphinx/writers/html.py

@@ -70,7 +70,9 @@ class HTMLTranslator(BaseTranslator):
         self.highlighter = builder.highlighter
         self.no_smarty = 0
         self.builder = builder
-        self.highlightlang = builder.config.highlight_language
+        self.highlightlang = self.highlightlang_base = \
+            builder.config.highlight_language
+        self.highlightopts = builder.config.highlight_options
         self.highlightlinenothreshold = sys.maxsize
         self.protect_literal_text = 0
         self.permalink_text = builder.config.html_add_permalinks
@@ -301,10 +303,15 @@ class HTMLTranslator(BaseTranslator):
             highlight_args['force'] = True
         if 'linenos' in node:
             linenos = node['linenos']
+        if lang is self.highlightlang_base:
+            # only pass highlighter options for original language
+            opts = self.highlightopts
+        else:
+            opts = {}
         def warner(msg):
             self.builder.warn(msg, (self.builder.current_docname, node.line))
         highlighted = self.highlighter.highlight_block(
-            node.rawsource, lang, warn=warner, linenos=linenos,
+            node.rawsource, lang, opts=opts, warn=warner, linenos=linenos,
             **highlight_args)
         starttag = self.starttag(node, 'div', suffix='',
                                  CLASS='highlight-%s' % lang)

sphinx/writers/latex.py

@@ -1378,10 +1378,15 @@ class LaTeXTranslator(nodes.NodeVisitor):
                 highlight_args['force'] = True
             if 'linenos' in node:
                 linenos = node['linenos']
+            if lang is self.hlsettingstack[0][0]:
+                # only pass highlighter options for original language
+                opts = self.builder.config.highlight_options
+            else:
+                opts = {}
             def warner(msg):
                 self.builder.warn(msg, (self.curfilestack[-1], node.line))
-            hlcode = self.highlighter.highlight_block(code, lang, warn=warner,
-                    linenos=linenos, **highlight_args)
+            hlcode = self.highlighter.highlight_block(code, lang, opts=opts,
+                    warn=warner, linenos=linenos, **highlight_args)
             # workaround for Unicode issue
             hlcode = hlcode.replace(u'€', u'@texteuro[]')
             # must use original Verbatim environment and "tabular" environment

tests/test_highlighting.py

@@ -62,6 +62,12 @@ def test_detect_interactive():
         assert ret.startswith("<div class=\"highlight\">")
 
 
+def test_lexer_options():
+    bridge = PygmentsBridge('html')
+    ret = bridge.highlight_block('//comment', 'php', opts={'startinline' : True})
+    assert '<span class="c1">//comment</span>' in ret
+
+
 def test_set_formatter():
     PygmentsBridge.html_formatter = MyFormatter
     try: