Creating LaTeX math macros within Sphinx

问题:

I'm writing some mathematical code in Python and using Sphinx to produce the documentation. I know that Sphinx can handle LaTeX code in Python docstrings; see http://sphinx.pocoo.org/latest/ext/math.html#module-sphinx.ext.mathbase. How can I create LaTeX macros, such as \newcommand{\cG}{\mathcal{G}}, to use in the Python docstrings?

回答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.

1. Create a file under the directory specified in the html_static_path configuration option (typically _static), say mathconf.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.

2. 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 from html_static_path to the _static directory under the build directory.

回答2:

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'  ##################################################### 

回答3:

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}}" 

文章来源: Creating LaTeX math macros within Sphinx