From ae696e39f7aabc2fd2aefe173c1cf40d7d4023cd Mon Sep 17 00:00:00 2001 From: alex Date: Mon, 8 Dec 2014 13:51:02 -0500 Subject: [PATCH 1/5] MAINT: update the list of sphinx math extensions, and use mathjax by default --- conf.py | 8 ++++++-- extensions.rst | 42 +++++++++++++----------------------------- 2 files changed, 19 insertions(+), 31 deletions(-) diff --git a/conf.py b/conf.py index 884098c..820c55d 100644 --- a/conf.py +++ b/conf.py @@ -20,18 +20,22 @@ # -- General configuration ----------------------------------------------------- +# this line tells sampledoc where the extensions begin + # 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', + 'sphinx.ext.mathjax', 'sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.inheritance_diagram', 'ipython_console_highlighting', 'numpydoc'] +# this line tells sampledoc where the extensions end + # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] diff --git a/extensions.rst b/extensions.rst index 6ed5a23..694da8c 100644 --- a/extensions.rst +++ b/extensions.rst @@ -34,21 +34,12 @@ file by adding the following. First we tell it where to find the extensions:: # os.path.abspath to make it absolute, like shown here. sys.path.append(os.path.abspath('sphinxext')) -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'] +And then we tell it what extensions to load: + +.. literalinclude:: conf.py + :language: python + :start-after: # this line tells sampledoc where the extensions begin + :end-before: # this line tells sampledoc where the extensions end 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 +106,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 From ee72affb5a4e2621dbf4b6ece1c1ddea5325555d Mon Sep 17 00:00:00 2001 From: alex Date: Mon, 8 Dec 2014 14:00:57 -0500 Subject: [PATCH 2/5] MAINT: manually merge the ipython directive change --- conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/conf.py b/conf.py index 820c55d..ab35019 100644 --- a/conf.py +++ b/conf.py @@ -26,7 +26,7 @@ # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. extensions = ['matplotlib.sphinxext.only_directives', 'matplotlib.sphinxext.plot_directive', - 'matplotlib.sphinxext.ipython_directive', + 'IPython.sphinxext.ipython_directive', 'sphinx.ext.mathjax', 'sphinx.ext.autodoc', 'sphinx.ext.doctest', From e1ffe88521664f2b6361f864db1baa34f4b23ad2 Mon Sep 17 00:00:00 2001 From: alex Date: Mon, 8 Dec 2014 14:22:16 -0500 Subject: [PATCH 3/5] MAINT: use IPython for ipython_console_highlighting --- conf.py | 2 +- sphinxext/ipython_console_highlighting.py | 114 ---------------------- 2 files changed, 1 insertion(+), 115 deletions(-) delete mode 100644 sphinxext/ipython_console_highlighting.py diff --git a/conf.py b/conf.py index ab35019..158d067 100644 --- a/conf.py +++ b/conf.py @@ -27,11 +27,11 @@ 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', - 'ipython_console_highlighting', 'numpydoc'] # this line tells sampledoc where the extensions end 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() From aa8f73811475c734879d0932da41ad0204a40c53 Mon Sep 17 00:00:00 2001 From: alex Date: Mon, 8 Dec 2014 15:44:25 -0500 Subject: [PATCH 4/5] MAINT: go back to copypasting code from conf.py into the extensions.rst file --- conf.py | 5 ----- extensions.rst | 19 +++++++++++++------ 2 files changed, 13 insertions(+), 11 deletions(-) diff --git a/conf.py b/conf.py index 158d067..0ff1f6d 100644 --- a/conf.py +++ b/conf.py @@ -20,8 +20,6 @@ # -- General configuration ----------------------------------------------------- -# this line tells sampledoc where the extensions begin - # 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', @@ -34,9 +32,6 @@ 'sphinx.ext.inheritance_diagram', 'numpydoc'] -# this line tells sampledoc where the extensions end - - # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] diff --git a/extensions.rst b/extensions.rst index 694da8c..be687ff 100644 --- a/extensions.rst +++ b/extensions.rst @@ -34,12 +34,19 @@ file by adding the following. First we tell it where to find the extensions:: # os.path.abspath to make it absolute, like shown here. sys.path.append(os.path.abspath('sphinxext')) -And then we tell it what extensions to load: - -.. literalinclude:: conf.py - :language: python - :start-after: # this line tells sampledoc where the extensions begin - :end-before: # this line tells sampledoc where the extensions end +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.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`. From c60f12b2bb8cba1bcc173483b72849cfa06a5fe3 Mon Sep 17 00:00:00 2001 From: alex Date: Mon, 8 Dec 2014 15:47:19 -0500 Subject: [PATCH 5/5] MAINT: update the doc to reflect the removal of a couple .py files from the sphinxext directory --- extensions.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/extensions.rst b/extensions.rst index be687ff..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