MathML in sphinx?

202 views
Skip to first unread message

Boris Kheyfets

unread,
Mar 5, 2013, 11:44:21 PM3/5/13
to sphinx...@googlegroups.com
I'm trying to make use of [sphinxcontrib-mathml](https://bitbucket.org/coh/sphinx-contrib-mathml/overview) extension. Here's a test document:

    .. _00mathml:

    ########
     MathML
    ########

    Inline test: :math:`a^2 + b^2 = c^2`

    Separate line test:

    .. math::

       a^2 + b^2 = c^2


but during compilation I get

    Exception occurred: File
    "/home/boris/.local/lib/python2.7/site-packages/docutils/nodes.py",
    line 1664, in unknown_departure % (self.__class__,
    node.__class__.__name__)) NotImplementedError:
    sphinx.writers.html.HTMLTranslator departing unknown node type:
    displaymath The full traceback has been saved in
    /tmp/sphinx-err-hi2qJ2.log, if you want to report the issue to the
    developers. Please also report this if it was a user error, so that
    a better error message can be provided next time. Either send bugs
    to the mailing list at
    <http://groups.google.com/group/sphinx-users/>, or report them in
    the tracker at <http://bitbucket.org/birkenfeld/sphinx/issues/>.
    Thanks! make: *** [html] Error 1

Does anyone succedeed in making use of the extension?

TP

unread,
Mar 6, 2013, 7:17:53 AM3/6/13
to sphinx...@googlegroups.com
On Tue, Mar 5, 2013 at 8:44 PM, Boris Kheyfets <kheyf...@gmail.com> wrote:
> I'm trying to make use of
> [sphinxcontrib-mathml](https://bitbucket.org/coh/sphinx-contrib-mathml/overview)
> extension.

Have you read the "Math support in Sphinx" documentation [1]?

[1] http://sphinx-doc.org/ext/math.html

Guenter Milde

unread,
Mar 6, 2013, 11:19:34 AM3/6/13
to sphinx...@googlegroups.com
On 2013-03-06, Boris Kheyfets wrote:

> [-- Type: text/plain, Encoding: --]

> I'm trying to make use of
> [sphinxcontrib-mathml](https://bitbucket.org/coh/sphinx-contrib-mathml/overview)
> extension. Here's a test document:

> .. _00mathml:

> ########
> MathML
> ########

> Inline test: :math:`a^2 + b^2 = c^2`

> Separate line test:

> .. math::

> a^2 + b^2 = c^2

Since Docutils Release 0.8 (2011-07-07)
mathematical formulas are supported without need for an extension.
The --math-output=mathml setting supports a subset of LaTeX math syntax
(including the above examples).

Günter



Boris Kheyfets

unread,
Mar 10, 2013, 3:46:23 PM3/10/13
to sphinx...@googlegroups.com
I saw it thanks. I've used MathJax -- but some times I need to have a lot of formulas in a document -- and then rendering them all takes a lot of time. As to pngmath -- I don't like the way it looks.

Boris.

Boris Kheyfets

unread,
Mar 10, 2013, 3:50:19 PM3/10/13
to sphinx...@googlegroups.com, mi...@users.sf.net
@Günter:

Thanks for a reply. It works if I compile with

rst2html.py --math-output=mathml

 -- but I can't get sphinx to output mathml. As far as I know sphinx doesn't use rst2html.py

With great respect,
Boris.

Guenter Milde

unread,
Mar 10, 2013, 4:21:37 PM3/10/13
to sphinx...@googlegroups.com
On 2013-03-10, Boris Kheyfets wrote:

>> Since Docutils Release 0.8 (2011-07-07)
>> mathematical formulas are supported without need for an extension.
>> The --math-output=mathml setting supports a subset of LaTeX math syntax
>> (including the above examples).

> ... It works if I compile with

> rst2html.py --math-output=mathml

> -- but I can't get sphinx to output mathml. As far as I know sphinx
> doesn't use rst2html.py

Both sphinx and rst2html.py use the same HTML writer which is part of Docutils
via the Docutils API (publish_...).

Without loading a Sphinx math extension, the Docutils version of the
math directive should be used - either MathJax or, with a current daily
snapshot (Docutils 0.11 [repository]) HTML+CSS.

I don't know how to configure Docutils when used from Sphinx. It may be
that the default configuration files are not used. However, it may be
worth a try to edit one of the `configuration files`__ and include

math-output=MathML

in the [HTML4css1 writer] section. This should do the trick.

With the "html4css1" writer, the resulting HTML document does not
validate, as there is no DTD for MathML + XHTML Transitional. However,
MathML-enabled browsers will render it fine.

Günter


__ http://docutils.sourceforge.net/docs/user/config.html#configuration-files

Boris Kheyfets

unread,
Mar 10, 2013, 5:29:49 PM3/10/13
to sphinx...@googlegroups.com, mi...@users.sf.net
I tried: it doesn't work:

I've made a file docutils.conf in the root dir of the doc

[html4css1 writer]
math-output=MathML


and in the html it gives -- I see that the math isn't converted to mathml.

With great respect,
Boris.

Guenter Milde

unread,
Mar 11, 2013, 4:34:09 AM3/11/13
to sphinx...@googlegroups.com
On 2013-03-10, Boris Kheyfets wrote:

> I tried: it doesn't work:

> I've made a file docutils.conf in the root dir of the doc

> [html4css1 writer]
> math-output=MathML

> and in the html it gives -- I see that the math isn't converted to mathml.

What then? Is it MathJax, HTML+CSS, PNG, LaTeX, or plain text?
Could you post an example?

Also, the "root dir of the doc" is not necessarily the right directory,
it should be "the working directory the conversion runs from" - I don't know
which this is with Sphinx. You may try with a config file in the home
directory or a system wide one.

Also, to differentiate, some other Docutils setting so we can find out if
the config file is ignored or just the math-output setting. (Remember
that Sphinx has it's own math support which overwrites the built-in
Docutils math directive and role.)

Günter

Boris Kheyfets

unread,
Mar 14, 2013, 12:29:09 PM3/14/13
to sphinx...@googlegroups.com
> What then? Is it MathJax, HTML+CSS, PNG, LaTeX, or plain text?
> Could you post an example?

Sure.

Here's a test rst:

Testing math directive:

.. math::

   a^2 + b^2 = c^2

Testing inline math: :math:`\sin\alpha`.


Here's html without docutils.conf:

<p>Testing math directive:</p>
<div class="math">
\begin{equation*}
a^2 + b^2 = c^2
\end{equation*}
</div>
<p>Testing inline math: <span class="math">\(\sin\alpha\)</span>
.</p>


I tried adding docutils.conf to

    • root dir of the doc
    • _static
    • _build

    In all of these cases I get the same html.

    --
    With respect,
    Boris.

    Reply all
    Reply to author
    Forward
    0 new messages