Add Sphinx.add_lexer().

CHANGES

@@ -4,6 +4,10 @@ Release 0.6 (in development)
 New features added
 ------------------
 
+* Extension API:
+
+  - Add Sphinx.add_lexer() to add custom Pygments lexers.
+
 * Other changes:
 
   - Allow giving config overrides for single dict keys on the command

doc/ext/appapi.rst

@@ -168,6 +168,13 @@ the following public API:
 
    .. versionadded:: 0.5
 
+.. method:: Sphinx.add_lexer(alias, lexer)
+
+   Use *lexer*, which must be an instance of a Pygments lexer class, to
+   highlight code blocks with the given language *alias*.
+
+   .. versionadded:: 0.6
+   
 .. method:: Sphinx.connect(event, callback)
 
    Register *callback* to be called when *event* is emitted.  For details on

sphinx/application.py

@@ -297,6 +297,12 @@ class Sphinx(object):
         StandaloneHTMLBuilder.script_files.append(
             posixpath.join('_static', filename))
 
+    def add_lexer(self, alias, lexer):
+        from sphinx.highlighting import lexers
+        if lexers is None:
+            return
+        lexers[alias] = lexer
+
 
 class TemplateBridge(object):
     """

sphinx/highlighting.py

@@ -30,6 +30,7 @@ try:
     from pygments.token import Generic, Comment, Number
 except ImportError:
     pygments = None
+    lexers = None
 else:
     class SphinxStyle(Style):
         """

tests/test_highlighting.py

@@ -0,0 +1,37 @@
+# -*- coding: utf-8 -*-
+"""
+    test_highlighting
+    ~~~~~~~~~~~~~~~~~
+
+    Test the Pygments highlighting bridge.
+
+    :copyright: 2008 by Georg Brandl.
+    :license: BSD.
+"""
+
+from util import *
+
+from pygments.lexer import RegexLexer
+from pygments.token import Text, Name
+
+from sphinx.highlighting import PygmentsBridge
+
+
+class MyLexer(RegexLexer):
+    name = 'testlexer'
+
+    tokens = {
+        'root': [
+            ('a', Name),
+            ('b', Text),
+        ],
+    }
+
+
+@with_app()
+def test_add_lexer(app):
+    app.add_lexer('test', MyLexer())
+
+    bridge = PygmentsBridge('html')
+    ret = bridge.highlight_block('ab', 'test')
+    assert '<span class="n">a</span>b' in ret