diff --git a/doc-requirements.txt b/doc-requirements.txt index 58a5c698043b..c0ee2014cf64 100644 --- a/doc-requirements.txt +++ b/doc-requirements.txt @@ -6,7 +6,7 @@ # Install the documentation requirements with: # pip install -r doc-requirements.txt # -sphinx>=1.3,!=1.5.0,!=1.6.4,!=1.7.3,<1.8 +sphinx>=1.3,!=1.5.0,!=1.6.4,!=1.7.3 colorspacious ipython ipywidgets diff --git a/doc/users/next_whats_new/2018-09-15-AL.rst b/doc/users/next_whats_new/2018-09-15-AL.rst new file mode 100644 index 000000000000..863d2f2b005b --- /dev/null +++ b/doc/users/next_whats_new/2018-09-15-AL.rst @@ -0,0 +1,12 @@ +:orphan: + +``:math:`` directive renamed to ``:mathmpl:`` +````````````````````````````````````````````` + +The ``:math:`` rst role provided by `matplotlib.sphinxext.mathmpl` has been +renamed to ``:mathmpl:`` to avoid conflicting with the ``:math:`` role that +Sphinx 1.8 provides by default. (``:mathmpl:`` uses Matplotlib to render math +expressions to images embedded in html, whereas Sphinx uses MathJax.) + +When using Sphinx<1.8, both names (``:math:`` and ``:mathmpl:``) remain +available for backcompatibility. diff --git a/lib/matplotlib/sphinxext/mathmpl.py b/lib/matplotlib/sphinxext/mathmpl.py index aad57f0de2e1..82ee3d71888d 100644 --- a/lib/matplotlib/sphinxext/mathmpl.py +++ b/lib/matplotlib/sphinxext/mathmpl.py @@ -1,10 +1,11 @@ +import hashlib import os import sys -from hashlib import md5 +import warnings from docutils import nodes from docutils.parsers.rst import directives -import warnings +import sphinx from matplotlib import rcParams from matplotlib.mathtext import MathTextParser @@ -70,7 +71,7 @@ def latex2png(latex, filename, fontset='cm'): def latex2html(node, source): inline = isinstance(node.parent, nodes.TextElement) latex = node['latex'] - name = 'math-%s' % md5(latex.encode()).hexdigest()[-10:] + name = 'math-%s' % hashlib.md5(latex.encode()).hexdigest()[-10:] destdir = os.path.join(setup.app.builder.outdir, '_images', 'mathmpl') if not os.path.exists(destdir): @@ -119,9 +120,13 @@ def depart_latex_math_latex(self, node): app.add_node(latex_math, html=(visit_latex_math_html, depart_latex_math_html), latex=(visit_latex_math_latex, depart_latex_math_latex)) - app.add_role('math', math_role) - app.add_directive('math', math_directive, + app.add_role('mathmpl', math_role) + app.add_directive('mathmpl', math_directive, True, (0, 0, 0), **options_spec) + if sphinx.version_info < (1, 8): + app.add_role('math', math_role) + app.add_directive('math', math_directive, + True, (0, 0, 0), **options_spec) metadata = {'parallel_read_safe': True, 'parallel_write_safe': True} return metadata diff --git a/tutorials/text/mathtext.py b/tutorials/text/mathtext.py index 9fafdcf1ed64..4ed6e297c73e 100644 --- a/tutorials/text/mathtext.py +++ b/tutorials/text/mathtext.py @@ -44,7 +44,7 @@ # # math text # plt.title(r'$\alpha > \beta$') # -# produces ":math:`\alpha > \beta`". +# produces ":mathmpl:`\alpha > \beta`". # # .. note:: # Mathtext should be placed between a pair of dollar signs ($). To @@ -77,9 +77,9 @@ # # \alpha_i > \beta_i # -# Some symbols automatically put their sub/superscripts under and over -# the operator. For example, to write the sum of :math:`x_i` from :math:`0` to -# :math:`\infty`, you could do:: +# Some symbols automatically put their sub/superscripts under and over the +# operator. For example, to write the sum of :mathmpl:`x_i` from :mathmpl:`0` +# to :mathmpl:`\infty`, you could do:: # # r'$\sum_{i=0}^\infty x_i$' # @@ -200,13 +200,13 @@ # ============================ ================================== # Command Result # ============================ ================================== -# ``\mathrm{Roman}`` :math:`\mathrm{Roman}` -# ``\mathit{Italic}`` :math:`\mathit{Italic}` -# ``\mathtt{Typewriter}`` :math:`\mathtt{Typewriter}` -# ``\mathcal{CALLIGRAPHY}`` :math:`\mathcal{CALLIGRAPHY}` +# ``\mathrm{Roman}`` :mathmpl:`\mathrm{Roman}` +# ``\mathit{Italic}`` :mathmpl:`\mathit{Italic}` +# ``\mathtt{Typewriter}`` :mathmpl:`\mathtt{Typewriter}` +# ``\mathcal{CALLIGRAPHY}`` :mathmpl:`\mathcal{CALLIGRAPHY}` # ============================ ================================== # -# .. role:: math-stix(math) +# .. role:: math-stix(mathmpl) # :fontset: stix # # When using the `STIX `_ fonts, you also have the choice of: @@ -294,16 +294,16 @@ # ============================== ================================= # Command Result # ============================== ================================= -# ``\acute a`` or ``\'a`` :math:`\acute a` -# ``\bar a`` :math:`\bar a` -# ``\breve a`` :math:`\breve a` -# ``\ddot a`` or ``\''a`` :math:`\ddot a` -# ``\dot a`` or ``\.a`` :math:`\dot a` -# ``\grave a`` or ``\`a`` :math:`\grave a` -# ``\hat a`` or ``\^a`` :math:`\hat a` -# ``\tilde a`` or ``\~a`` :math:`\tilde a` -# ``\vec a`` :math:`\vec a` -# ``\overline{abc}`` :math:`\overline{abc}` +# ``\acute a`` or ``\'a`` :mathmpl:`\acute a` +# ``\bar a`` :mathmpl:`\bar a` +# ``\breve a`` :mathmpl:`\breve a` +# ``\ddot a`` or ``\''a`` :mathmpl:`\ddot a` +# ``\dot a`` or ``\.a`` :mathmpl:`\dot a` +# ``\grave a`` or ``\`a`` :mathmpl:`\grave a` +# ``\hat a`` or ``\^a`` :mathmpl:`\hat a` +# ``\tilde a`` or ``\~a`` :mathmpl:`\tilde a` +# ``\vec a`` :mathmpl:`\vec a` +# ``\overline{abc}`` :mathmpl:`\overline{abc}` # ============================== ================================= # # In addition, there are two special accents that automatically adjust @@ -312,8 +312,8 @@ # ============================== ================================= # Command Result # ============================== ================================= -# ``\widehat{xyz}`` :math:`\widehat{xyz}` -# ``\widetilde{xyz}`` :math:`\widetilde{xyz}` +# ``\widehat{xyz}`` :mathmpl:`\widehat{xyz}` +# ``\widetilde{xyz}`` :mathmpl:`\widetilde{xyz}` # ============================== ================================= # # Care should be taken when putting accents on lower-case i's and j's.