Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add support for html_math_renderer = 'mathml' #251

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add support for html_math_renderer = 'mathml' #251

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 1 addition & 3 deletions docs/additional_samples.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -211,7 +211,7 @@ Math

.. math::

(a + b)^2 = a^2 + 2ab + b^2
(a + b)^2 = a^2 + 2ab + b^2 \\
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It might be worth noting when the escaped line breaks are needed/useful in a doc dedicated to this theme-ext


(a - b)^2 = a^2 - 2ab + b^2

Expand All @@ -227,10 +227,8 @@ Math
.. math::
:nowrap:

\begin{eqnarray}
y & = & ax^2 + bx + c \\
f(x) & = & x^2 + 2xy + y^2
\end{eqnarray}



Expand Down
2 changes: 1 addition & 1 deletion docs/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,6 @@
"sphinx.ext.intersphinx",
"sphinx.ext.napoleon",
"sphinx.ext.todo",
"sphinx.ext.mathjax",
"sphinx.ext.viewcode",
"sphinx_immaterial.theme_result",
"sphinx_immaterial.kbd_keys",
Expand Down Expand Up @@ -97,6 +96,7 @@
html_title = "Sphinx-Immaterial"
html_favicon = "_static/images/favicon.ico" # colored version of material/bookshelf.svg
html_logo = "_static/images/Ybin.gif" # from https://gifer.com/en/Ybin
html_math_renderer = "mathml"

# -- HTML theme specific settings ------------------------------------------------

Expand Down
1 change: 1 addition & 0 deletions docs/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -141,4 +141,5 @@ or ``theme.conf`` for more details.
rst_basics
rst-cheatsheet/rst-cheatsheet
additional_samples
math
myst_typography
1,182 changes: 1,182 additions & 0 deletions docs/math.rst
View file
Open in desktop

Large diffs are not rendered by default.

2 changes: 2 additions & 0 deletions sphinx_immaterial/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -301,6 +301,8 @@ def setup(app: Sphinx):
)
app.add_html_theme("sphinx_immaterial", os.path.abspath(os.path.dirname(__file__)))

app.setup_extension("sphinx_immaterial.mathml_math_renderer")

# register our custom directives/roles that are tied to this theme
app.setup_extension("sphinx_immaterial.content_tabs")
app.setup_extension("sphinx_immaterial.mermaid_diagrams")
Expand Down
40 changes: 40 additions & 0 deletions sphinx_immaterial/mathml_math_renderer.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
"""Extension that enables docutils' MathML-based math rendering."""

import docutils.nodes
import docutils.utils.math
from docutils.writers._html_base import HTMLTranslator as BaseHTMLTranslator
from sphinx.application import Sphinx

# Sphinx overrides Docutils' math rendering. Here, we override Sphinx's
# override to revert to docutils' math rendering.


def visit_math(self: BaseHTMLTranslator, node: docutils.nodes.math):
self.math_output = "mathml"
self.math_output_options = []
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this be extended to user confval(s)? Does this directly influence the docutils' converter used?

Copy link
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is basically equivalent to putting:

[html writers]
math_output: mathml

in a docutils.conf file next to the conf.py file.

There is one option that could be specified, an external LaTeX-syntax to MathML converter program to use in place of the one that is built into docutils. Probably there should be a config option for that.

Alternatively this extension could be renamed "docutils_math_renderer" and we could require the user to create the separate docutils.conf file to specify the math format. However, it seems unlikely that a user would want to use any of the docutils math formats other than mathml:

  • the mathjax format is already separately supported by sphinx, so I don't think there is any point in supporting that;
  • I don't know about the "HTML" format, but if we wanted to support that, we'd have to arrange to include the appropriate math.css stylesheet.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm really just working with the info from here. I think it would be fine to only use the docutils converter script (latex2mathml). But I was thinking it might be useful if a user already has external converter installed (like pandoc or blahxml) and might want to use that instead.

BaseHTMLTranslator.visit_math(self, node)


def visit_math_block(self: BaseHTMLTranslator, node: docutils.nodes.math_block):
self.math_output = "mathml"
self.math_output_options = []
# Note: We can't call `BaseHTMLTranslator.visit_math_block` here, because
# that just forwards to `self.visit_math`, which ultimately calls back into
# our `visit_math` function defined above but without the `math_env`
# argument.
BaseHTMLTranslator.visit_math(
self, node, math_env=docutils.utils.math.pick_math_environment(node.astext())
)


def setup(app: Sphinx):
"""Setup the extension."""
app.add_html_math_renderer(
"mathml",
(visit_math, None), # type: ignore[arg-type]
(visit_math_block, None), # type: ignore[arg-type]
)
return {
"parallel_read_safe": True,
"parallel_write_safe": True,
}
1 change: 1 addition & 0 deletions src/assets/stylesheets/main.scss
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -85,3 +85,4 @@

@import "main/sphinx";
@import "main/api";
@import "main/mathml";
50 changes: 50 additions & 0 deletions src/assets/stylesheets/main/_mathml.scss
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
math .boldsymbol {
font-weight: bold;
}

mtable[columnalign="right left"] {
> mtr {
> mtd:nth-child(1) {
text-align: -webkit-right;
}
> mtd:nth-child(2) {
text-align: -webkit-left;
}
}
}

mtable[columnalign="right left right"] {
> mtr {
> mtd:nth-child(1) {
text-align: -webkit-right;
}
> mtd:nth-child(2) {
text-align: -webkit-left;
}
> mtd:nth-child(3) {
text-align: -webkit-right;
}
}
}

mtable[columnspacing="0 2em"] {
> mtr {
> mtd:nth-child(1) {
padding-left: 0px;
padding-right: 0px;
}
> mtd:nth-child(2) {
padding-left: 0px;
padding-right: 2em;
}
}
}

mtable[columnspacing="0"] {
> mtr {
> mtd {
padding-left: 0px;
padding-right: 0px;
}
}
}