Création de macros mathématiques LaTeX dans Sphinx

Question

Je suis en train d'écrire un code mathématique en Python et j'utilise Sphinx pour produire la documentation. Je sais que Sphinx peut gérer le code LaTeX dans les docstrings Python ; voir https://www.sphinx-doc.org/en/master/usage/extensions/math.html#module-sphinx.ext.mathbase . Comment puis-je créer des macros LaTeX, telles que \newcommand{\cG}{\mathcal{G}} à utiliser dans les docstrings Python ?

Answer 1

Si vous utilisez MathJax, voici une solution possible. Je suis toujours à la recherche d'une solution plus agréable, mais cela pourrait vous aider si vous avez besoin d'une solution rapide.

1. Créez un fichier sous le répertoire spécifié dans l'option html_static_path option de configuration (généralement _static ), disons mathconf.js . Il contiendra la configuration JS pour MathJax. Par exemple (à partir du Documentation MathJax ):

   MathJax.Hub.Config({
     TeX: {
       Macros: {
         RR: '{\\bf R}',
         bold: ['{\\bf #1}', 1]
       }
     }
   });

   Vous pouvez ajouter d'autres commandes en suivant la syntaxe ci-dessus. Le contenu affiché définit les macros \RR y \bold{#1} ce dernier acceptant un argument.

2. Ajouter un layout.html au niveau du _templates répertoire. L'idée est d'étendre le thème actuel, afin qu'il recherche le fichier de configuration MathJax précédent. Ainsi, le contenu est :

   {% extends "!layout.html" %}
   {% set script_files = script_files + ["_static/mathconf.js"] %}

   Notez que dans ce cas, il es le site _static car, dans ce cas, il s'agit de l'endroit où chercher. après la construction. Sphinx aura déplacé le fichier de html_static_path a la _static sous le répertoire de construction.

Answer 2

Aha, j'ai trouvé une solution qui fonctionne avec l'extension Sphinx pngmath. C'est l'astuce qu'utilise Sage (logiciel de mathématiques open source) ; inspiration de http://www.sagemath.org/doc/reference/sage/misc/latex_macros.html .

Pour ajouter vos propres macros Latex à un document Sphinx :

1) Créez un fichier, disons 'latex_macros.sty', contenant vos macros (une par ligne), et placez-le dans, disons, le même répertoire que votre fichier Sphinx conf.py ;

2) Ajoutez le code suivant à votre fichier conf.py de Sphinx :

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

#####################################################

Answer 3

Si vous utilisez l'extension pngmath, vous pouvez la mettre dans le préambule en insérant ceci dans le fichier conf.py script :

pngmath_latex_preamble = r"\newcommand{\cG}{\mathcal{G}}"

Answer 4

Pour ajouter à la réponse de @Keta depuis août 2018 et ce commit (. https://github.com/sphinx-doc/sphinx/pull/5230/files ), vous pouvez utiliser mathjax_config dans le fichier conf.py selon la documentation ( http://www.sphinx-doc.org/en/master/usage/extensions/math.html?#confval-mathjax_config )

Ainsi, par exemple, on peut ajouter ce qui suit,

mathjax_config = {                  
    "TeX": {                        
        "Macros": {                 
            "RR": '{\\bf R}',       
            "bold": ['{\\bf #1}',1] 
            }                       
        }                           
    }

Answer 5

La solution proposée a été testée sur sphinx-doc 2.4.3 (par ex, sphinx-quickstart --version )

Sphinx-doc permet des manipulations supplémentaires avec MathJax par le biais de mathjax_config . Le but final est de mettre en œuvre ce qui suit dans conf.py :

mathjax_config = {
    'TeX': {
        'Macros': {
            # Math notation
            "Z": "\\mathbb{Z}",                                    # set of integers
            # MoA notations
            "minus": "{}^{\\boldsymbol{\\mbox{-}}\\!}",            # scalar negation operator
        }
   }
}

Nous pouvons le faire manuellement comme ci-dessus. Cependant, nous pouvons faire mieux en remplissant automatiquement le fichier mathjax_config via l'analyse d'un fichier séparé .tex qui contient toutes les macro-commandes.

Par exemple, j'ai mathsymbols.tex se trouve au même niveau que conf.py dont le contenu ressemble à celui ci-dessous :

\DeclareRobustCommand{\ojoin}{\rule[-0.12ex]{.3em}{.4pt}\llap{\rule[1.2ex]{.3em}{.4pt}}}
\newcommand{\leftouterjoin}{\mathrel{\ojoin\mkern-6.5mu\Join}}
\newcommand{\rightouterjoin}{\mathrel{\Join\mkern-6.5mu\ojoin}}
\newcommand{\fullouterjoin}{\mathrel{\ojoin\mkern-6.5mu\Join\mkern-6.5mu\ojoin}}

Ensuite, à l'intérieur conf.py on peut écrire :

mathjax_config = { 'TeX': {'Macros': {}}}

with open('mathsymbols.tex', 'r') as f:
    for line in f:
        macros = re.findall(r'\\(DeclareRobustCommand|newcommand){\\(.*?)}(\[(\d)\])?{(.+)}', line)
        for macro in macros:
            if len(macro[2]) == 0:
                mathjax_config['TeX']['Macros'][macro[1]] = "{"+macro[4]+"}"
            else:
                mathjax_config['TeX']['Macros'][macro[1]] = ["{"+macro[4]+"}", int(macro[3])]

pour remplir automatiquement mathjax_config et nous avons terminé.

Avec l'exemple ci-dessus, nous pouvons utiliser \leftouterjoin Macro LaTeX dans sphinx-doc.