Add Sphinx.add_lexer().

5 files changed, 55 insertions, 0 deletions

diff --git a/CHANGES b/CHANGES
index 5d9bc20c..b45ce66c 100644
--- a/CHANGES
+++ b/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
diff --git a/doc/ext/appapi.rst b/doc/ext/appapi.rst
index 355e42bd..3dd5282b 100644
--- a/doc/ext/appapi.rst
+++ b/doc/ext/appapi.rst
@@ -167,6 +167,13 @@ the following public API:
    :confval:`the docs for the config value <html_static_path>`.
 
    .. 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)
 
diff --git a/sphinx/application.py b/sphinx/application.py
index 6c644bbe..f7c57592 100644
--- a/sphinx/application.py
+++ b/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):
     """
diff --git a/sphinx/highlighting.py b/sphinx/highlighting.py
index 3017133a..d85aac23 100644
--- a/sphinx/highlighting.py
+++ b/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):
         """
diff --git a/tests/test_highlighting.py b/tests/test_highlighting.py
new file mode 100644
index 00000000..5c353946
--- /dev/null
+++ b/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