Creating LaTeX math macros within Sphinx
Aha, i found a solution that works with the Sphinx pngmath extension. It's the trick that Sage (open source mathematics software) uses; inspiration from http://www.sagemath.org/doc/reference/sage/misc/latex_macros.html.
To add your own Latex macros to a Sphinx document:
1) Make a file, say 'latex_macros.sty', containing your macros (one per line), and put it in, say, the same directory as your Sphinx conf.py file;
2) Add the following code to your Sphinx conf.py file:
# Additional stuff for the LaTeX preamble.
latex_elements['preamble'] = '\usepackage{amsmath}\n\usepackage{amssymb}\n'
#####################################################
# add LaTeX macros
f = file('latex_macros.sty')
try:
pngmath_latex_preamble # check whether this is already defined
except NameError:
pngmath_latex_preamble = ""
for macro in f:
# used when building latex and pdf versions
latex_elements['preamble'] += macro + '\n'
# used when building html version
pngmath_latex_preamble += macro + '\n'
#####################################################
To add to @Keta's answer since Aug 2018 and this commit (https://github.com/sphinx-doc/sphinx/pull/5230/files) you can use mathjax_config
in the conf.py according to the documentation (http://www.sphinx-doc.org/en/master/usage/extensions/math.html?#confval-mathjax_config)
So for example the following can be added,
mathjax_config = {
"TeX": {
"Macros": {
"RR": '{\\bf R}',
"bold": ['{\\bf #1}',1]
}
}
}
If you are using MathJax, here's a possible solution. I'm still looking for a nicer solution, but it might help if you need a quick hack.
Create a file under the directory specified in the
html_static_path
configuration option (typically_static
), saymathconf.js
. This will contain the JS configuration for MathJax. For instance (from the MathJax documentation):MathJax.Hub.Config({ TeX: { Macros: { RR: '{\\bf R}', bold: ['{\\bf #1}', 1] } } });
You can add more commands following the syntax above. The contents shown define the macros
\RR
and\bold{#1}
, this last one accepting one argument.Add a
layout.html
file at the_templates
directory. The idea is to extend the current theme, so it searches the previous MathJax configuration file. Thus, the contents are:{% extends "!layout.html" %} {% set script_files = script_files + ["_static/mathconf.js"] %}
Note that in this case it is the
_static
directory, because in this case it refers to where to search after the build. Sphinx will have moved the file fromhtml_static_path
to the_static
directory under the build directory.
If you're using the pngmath extension, you can put that in the preamble by inserting this into the conf.py script:
pngmath_latex_preamble = r"\newcommand{\cG}{\mathcal{G}}"