diff --git a/conf.py b/conf.py index 884098c..0ff1f6d 100644 --- a/conf.py +++ b/conf.py @@ -22,17 +22,16 @@ # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['matplotlib.sphinxext.mathmpl', - 'matplotlib.sphinxext.only_directives', +extensions = ['matplotlib.sphinxext.only_directives', 'matplotlib.sphinxext.plot_directive', - 'matplotlib.sphinxext.ipython_directive', + 'IPython.sphinxext.ipython_directive', + 'IPython.sphinxext.ipython_console_highlighting', + 'sphinx.ext.mathjax', 'sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.inheritance_diagram', - 'ipython_console_highlighting', 'numpydoc'] - # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] diff --git a/extensions.rst b/extensions.rst index 6ed5a23..61792ca 100644 --- a/extensions.rst +++ b/extensions.rst @@ -18,8 +18,7 @@ our :file:`sampledoc` project :file:`sphinxext` directory:: home:~/tmp/sampledoc> mkdir sphinxext home:~/tmp/sampledoc> cp ../sampledoc_tut/sphinxext/*.py sphinxext/ home:~/tmp/sampledoc> ls sphinxext/ - apigen.py docscrape_sphinx.py ipython_console_highlighting.py - docscrape.py inheritance_diagram.py numpydoc.py + apigen.py docscrape.py docscrape_sphinx.py numpydoc.py In addition to the builtin matplotlib extensions for embedding pyplot plots and rendering math with matplotlib's native math engine, we also @@ -36,19 +35,17 @@ file by adding the following. First we tell it where to find the extensions:: And then we tell it what extensions to load:: - # Add any Sphinx extension module names here, as strings. They can - # be extensions coming with Sphinx (named 'sphinx.ext.*') or your - # custom ones. - extensions = [ - 'matplotlib.sphinxext.mathmpl', - 'matplotlib.sphinxext.only_directives', - 'matplotlib.sphinxext.plot_directive', - 'matplotlib.sphinxext.ipython_directive', - 'sphinx.ext.autodoc', - 'sphinx.ext.doctest', - 'ipython_console_highlighting', - 'inheritance_diagram', - 'numpydoc'] + # Add any Sphinx extension module names here, as strings. They can be extensions + # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. + extensions = ['matplotlib.sphinxext.only_directives', + 'matplotlib.sphinxext.plot_directive', + 'IPython.sphinxext.ipython_directive', + 'IPython.sphinxext.ipython_console_highlighting', + 'sphinx.ext.mathjax', + 'sphinx.ext.autodoc', + 'sphinx.ext.doctest', + 'sphinx.ext.inheritance_diagram', + 'numpydoc'] Now let's look at some of these in action. You can see the literal source for this file at :ref:`extensions-literal`. @@ -115,25 +112,18 @@ which is rendered as W^{3\beta}_{\delta_1 \rho_1 \sigma_2} \approx U^{3\beta}_{\delta_1 \rho_1} -This documentation framework includes a Sphinx extension, -:file:`sphinxext/mathmpl.py`, that uses matplotlib to render math -equations when generating HTML, and LaTeX itself when generating a -PDF. This can be useful on systems that have matplotlib, but not -LaTeX, installed. To use it, add ``mathmpl`` to the list of -extensions in :file:`conf.py`. +Recent versions of Sphinx include built-in support for math. +There are three flavors: -Current SVN versions of Sphinx now include built-in support for math. -There are two flavors: + - sphinx.ext.pngmath: uses dvipng to render the equation - - pngmath: uses dvipng to render the equation + - sphinx.ext.mathjax: renders the math in the browser using Javascript - - jsmath: renders the math in the browser using Javascript + - sphinx.ext.jsmath: it's an older code, but it checks out -To use these extensions instead, add ``sphinx.ext.pngmath`` or -``sphinx.ext.jsmath`` to the list of extensions in :file:`conf.py`. +Additionally, matplotlib has its own math support: -All three of these options for math are designed to behave in the same -way. + - matplotlib.sphinxext.mathmpl See the matplotlib `mathtext guide `_ for lots diff --git a/sphinxext/ipython_console_highlighting.py b/sphinxext/ipython_console_highlighting.py deleted file mode 100644 index 217b779..0000000 --- a/sphinxext/ipython_console_highlighting.py +++ /dev/null @@ -1,114 +0,0 @@ -"""reST directive for syntax-highlighting ipython interactive sessions. - -XXX - See what improvements can be made based on the new (as of Sept 2009) -'pycon' lexer for the python console. At the very least it will give better -highlighted tracebacks. -""" - -#----------------------------------------------------------------------------- -# Needed modules - -# Standard library -import re - -# Third party -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 - -#----------------------------------------------------------------------------- -# Global constants -line_re = re.compile('.*?\n') - -#----------------------------------------------------------------------------- -# Code begins - classes and functions - -class IPythonConsoleLexer(Lexer): - """ - For IPython console output or doctests, such as: - - .. sourcecode:: ipython - - In [1]: a = 'foo' - - In [2]: a - Out[2]: 'foo' - - In [3]: print a - foo - - In [4]: 1 / 0 - - Notes: - - - Tracebacks are not currently supported. - - - It assumes the default IPython prompts, not customized ones. - """ - - 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: - # Use the 'error' token for output. We should probably make - # our own token, but error is typicaly in a bright color like - # red, so it works fine for our output prompts. - insertions.append((len(curcode), - [(0, Generic.Error, 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 - - -def setup(app): - """Setup as a sphinx extension.""" - - # This is only a lexer, so adding it below to pygments appears sufficient. - # But if somebody knows that the right API usage should be to do that via - # sphinx, by all means fix it here. At least having this setup.py - # suppresses the sphinx warning we'd get without it. - pass - -#----------------------------------------------------------------------------- -# Register the extension as a valid pygments lexer -highlighting.lexers['ipython'] = IPythonConsoleLexer()