Add support for syntax-highlighting ipython console sessions.

mdboom · mdboom · commit 2c895b326367 · 2008-05-23T14:53:33.000Z
svn path=/trunk/matplotlib/; revision=5227
diff --git a/doc/sphinxext/ipython_console_highlighting.py b/doc/sphinxext/ipython_console_highlighting.py
@@ -0,0 +1,75 @@
+from pygments.lexer import Lexer, do_insertions
+from pygments.lexers.agile import PythonConsoleLexer, PythonLexer, \
+    PythonTracebackLexer
+from pygments.token import Comment, Generic
+from sphinx import highlighting
+import re
+
+line_re = re.compile('.*?\n')
+
+class IPythonConsoleLexer(Lexer):
+    """
+    For IPython console output or doctests, such as:
+
+    Tracebacks are not currently supported.
+
+    .. sourcecode:: pycon
+
+      In [1]: a = 'foo'
+
+      In [2]: a
+      Out[2]: 'foo'
+
+      In [3]: print a
+      foo
+
+      In [4]: 1 / 0
+    """
+    name = 'IPython console session'
+    aliases = ['ipython']
+    mimetypes = ['text/x-ipython-console']
+    input_prompt = re.compile("(In \[[0-9]+\]: )|(   \.\.\.+:)")
+    output_prompt = re.compile("(Out\[[0-9]+\]: )|(   \.\.\.+:)")
+    continue_prompt = re.compile("   \.\.\.+:")
+    tb_start = re.compile("\-+")
+
+    def get_tokens_unprocessed(self, text):
+        pylexer = PythonLexer(**self.options)
+        tblexer = PythonTracebackLexer(**self.options)
+
+        curcode = ''
+        insertions = []
+        for match in line_re.finditer(text):
+            line = match.group()
+            input_prompt = self.input_prompt.match(line)
+            continue_prompt = self.continue_prompt.match(line.rstrip())
+            output_prompt = self.output_prompt.match(line)
+            if line.startswith("#"):
+                insertions.append((len(curcode),
+                                   [(0, Comment, line)]))
+            elif input_prompt is not None:
+                insertions.append((len(curcode),
+                                   [(0, Generic.Prompt, input_prompt.group())]))
+                curcode += line[input_prompt.end():]
+            elif continue_prompt is not None:
+                insertions.append((len(curcode),
+                                   [(0, Generic.Prompt, continue_prompt.group())]))
+                curcode += line[continue_prompt.end():]
+            elif output_prompt is not None:
+                insertions.append((len(curcode),
+                                   [(0, Generic.Output, output_prompt.group())]))
+                curcode += line[output_prompt.end():]
+            else:
+                if curcode:
+                    for item in do_insertions(insertions,
+                                              pylexer.get_tokens_unprocessed(curcode)):
+                        yield item
+                        curcode = ''
+                        insertions = []
+                yield match.start(), Generic.Output, line
+        if curcode:
+            for item in do_insertions(insertions,
+                                      pylexer.get_tokens_unprocessed(curcode)):
+                yield item
+
+highlighting.lexers['ipython'] = IPythonConsoleLexer()
diff --git a/doc/users_guide/artist_api_tut.txt b/doc/users_guide/artist_api_tut.txt
@@ -61,7 +61,9 @@ fig.add_subplot call above (remember Subplot is just a subclass of
 Axes) and when you call ax.plot, it creates a Line2D instance and adds
 it the the Axes.lines list.  In the interactive ipython session below,
 you can see that Axes.lines list is length one and contains the same
-line that was returned by the "line, ax.plot(x, y, 'o')" call::
+line that was returned by the "line, ax.plot(x, y, 'o')" call:
+
+.. sourcecode:: ipython
 
     In [101]: ax.lines[0]
     Out[101]: <matplotlib.lines.Line2D instance at 0x19a95710>
@@ -159,8 +161,9 @@ If you are working interactively at the python shell, a handy way to
 inspect the artist properties is to use the matplotlib.artist.getp
 method, which lists the properties and their values (simply "getp") in
 pylab.  This works for classes derived from Artist as well, eg Figure
-and Rectangle.  Here are the Figure rectangle properties mentioned above::
+and Rectangle.  Here are the Figure rectangle properties mentioned above:
 
+.. sourcecode:: ipython
 
     In [149]: matplotlib.artist.getp(fig.figurePatch)
 	alpha = 1.0
@@ -218,7 +221,9 @@ contains everything in the figure.  The background of the figure is a
 Rectangle which is stored in fig.figurePatch (where fig is your Figure
 instance).  As you add subplots (fig.add_subplot) and axes
 (ax.add_axes)to the figure these will be appended to the fig.axes
-list.  These are also returned by the methods that create them::
+list.  These are also returned by the methods that create them:
+
+.. sourcecode:: ipython
 
     In [156]: fig = plt.figure()
 
@@ -232,7 +237,6 @@ list.  These are also returned by the methods that create them::
     In [160]: print fig.axes
     [<matplotlib.axes.Subplot instance at 0xd54b26c>, <matplotlib.axes.Axes instance at 0xd3f0b2c>]
 
-
 Because the figure maintains the concept of the "current axes" (see
 Figure.gca and Figure.sca) to support the pylab/pyplot state machine,
 you should not insert or remove axes directly from the axes list, but
@@ -253,7 +257,9 @@ want) but you can control this by setting the transform property of
 the Artist you are adding to the figure.  More useful is "figure
 coordinates" where 0,0 is the bottom, left of the figure and 1,1 is
 the top, right of the figure which you can obtain by setting the
-Artist transform to fig.transFigure::
+Artist transform to fig.transFigure:
+
+.. sourcecode:: ipython
 
     In [191]: fig = plt.figure()
 
@@ -303,7 +309,9 @@ When you call a plotting method, eg the canonical "ax.plot" and pass
 in arrays or list of values, the method will a matplotlib.lines.Line2D
 instance, update the line with all the Line2D properties passed as
 keyword arguments, add the line to the Axes.lines container, and
-returns it to you::
+returns it to you:
+
+.. sourcecode:: ipython
 
     In [213]: x, y = np.random.rand(2, 100)
 
@@ -312,14 +320,17 @@ returns it to you::
 ax.plot returns a list of lines because you can pass in multiple x, y
 pairs to plot, and we are unpacking the first element of the length
 one list into the line variable.  The line has been added to the
-ax.lines list::
+ax.lines list:
 
+.. sourcecode:: ipython
 
     In [229]: print ax.lines
     [<matplotlib.lines.Line2D instance at 0xd378b0c>]
 
 Similarly, methods that create patches, like ax.bar creates a list of
-rectangles, will add the patches to the ax.patches list::
+rectangles, will add the patches to the ax.patches list:
+
+.. sourcecode:: ipython
 
     In [233]: n, bins, rectangles = ax.hist(np.random.randn(1000), 50, facecolor='yellow')
 
@@ -338,7 +349,9 @@ auto-scaling, so that the view limits can be adjusted to contain the
 plotted data.  You can, nonetheless, create objects yourself and add
 them directly to the Axes using helper methods like ax.add_line and
 ax.add_patch.  Here is an annotated interactive session illustrating
-what is going on::
+what is going on:
+
+.. sourcecode:: ipython
 
     In [261]: fig = plt.figure()
 
@@ -460,7 +473,9 @@ and zooming), you should access the lists of major and minor ticks
 through their accessor methods axis.get_major_ticks() and
 axis.get_minor_ticks().  Although the ticks contain all the primitives
 and will be covered below, the Axis methods contain accessor methods
-to return the tick lines, tick labels, tick locations etc....::
+to return the tick lines, tick labels, tick locations etc....:
+
+.. sourcecode:: ipython
 
     In [285]: axis = ax.xaxis
 
diff --git a/doc/users_guide/conf.py b/doc/users_guide/conf.py
@@ -18,6 +18,10 @@
 # absolute, like shown here.
 sys.path.append(os.path.abspath('../sphinxext'))
 
+# Import support for ipython console session syntax highlighting (lives
+# in the sphinxext directory defined above)
+import ipython_console_highlighting
+
 # General configuration
 # ---------------------
 
