Suporte matemático para saídas HTML no Sphinx

Adicionado na versão 0.5.

Alterado na versão 1.8: O suporte matemático para construtores não-HTML é integrado ao sphinx-core. Portanto, a extensão mathbase não é mais necessária.

Como a notação matemática não é suportada nativamente pelo HTML de forma alguma, o Sphinx fornece um suporte matemático para o documento HTML com várias extensões. Estas usam o reStructuredText math directive e role.

sphinx.ext.imgmath – Renderizar math com imagens

Adicionado na versão 1.4.

Essa extensão renderiza math via LaTeX e dvipng ou dvisvgm em imagens PNG ou SVG. Isso significa que no computador onde esses documentos serão construídos, devem ter esses programas disponíveis.

Existem vários valores de configuração que você pode definir para influenciar como as imagens são construídas:

imgmath_image_format
Type:
'png' | 'svg'
Default:
'png'

The output image format. It should be either 'png' or 'svg'. The image is produced by first executing latex on the TeX mathematical mark-up then (depending on the requested format) either dvipng or dvisvgm.

imgmath_use_preview
Type:
bool
Default:
False

dvipng e dvisvgm ambos têm a capacidade de coletar do LaTeX a profundidade da matemática renderizada: uma imagem inline deve usar essa profundidade em um estilo vertical-align para ficar corretamente alinhado com o texto ao redor.

Esse mecanismo requer o LaTeX preview package (disponível como preview-latex-style no Ubuntu xenial). Portanto, o padrão para essa opção é False, mas é altamente recomendável configurá-la como True.

Alterado na versão 2.2: Esta opção pode ser usada com o 'svg' imgmath_image_format.

imgmath_add_tooltips
Type:
bool
Default:
True

If false, do not add the LaTeX code as an “alt” attribute for math images.

imgmath_font_size
Type:
int
Default:
12

The font size (in pt) of the displayed math. This must be a positive integer.

imgmath_latex
Type:
str
Default:
'latex'

The command name with which to invoke LaTeX. You may need to set this to a full path if latex is not in the executable search path.

Como essa configuração não é portável de um sistema para outro, não é muito útil configurar no conf.py; em vez disso, use o comando do sphinx-build via -D é mais eficaz, como isso:

sphinx-build -M html -D imgmath_latex=C:\tex\latex.exe . _build

Esse valor deve conter somente o PATH para o programa LaTeX executável, sem nenhum argumento; usar imgmath_latex_args para esse propósito.

Dica

Para usar fontes Math da OpenType com unicode-math, através de um imgmath_latex_preamble personalizado, você pode definir imgmath_latex para 'dvilualatex', mas deve então definir imgmath_image_format para 'svg'. Nota: isso só foi testado com dvisvgm 3.0.3. Ele aumenta significativamente a duração da produção de imagens em comparação ao uso do 'latex' padrão com fontes matemáticas TeX tradicionais.

Dica

Algumas marcações LaTeX sofisticadas (foi relatado um exemplo que usava TikZ para adicionar várias decorações à equação) requerem múltiplas execuções do executável LaTeX. Para lidar com isso, defina esta configuração como 'latexmk' (ou um caminho completo para ele), pois este script Perl escolhe de forma confiável e dinâmica quantas execuções de latex são necessárias.

Alterado na versão 6.2.0: Usar 'xelatex' (ou um caminho completo para ele) agora é suportado. Mas você deve então adicionar '-no-pdf' à lista imgmath_latex_args de opções de comando. imgmath_image_format com 'svg' é obrigatório. Além disso, você pode precisar que o binário dvisvgm seja relativamente recente (o teste foi feito apenas com sua versão 3.0.3).

Nota

Em relação à nota anterior, atualmente não é suportado o uso de latexmk com a opção -xelatex.

imgmath_latex_args
Type:
Sequence[str]
Default:
()

Additional arguments to give to latex, as a list.

imgmath_latex_preamble
Type:
str
Default:
''

Additional LaTeX code to put into the preamble of the LaTeX files used to translate the math snippets. Use it e.g. to add packages which modify the fonts used for math, such as '\\usepackage{newtxsf}' for sans-serif fonts, or '\\usepackage{fouriernc}' for serif fonts. Indeed, the default LaTeX math fonts have rather thin glyphs which (in HTML output) often do not match well with the font for text.

imgmath_dvipng
Type:
str
Default:
'dvipng'

The command name to invoke dvipng. You may need to set this to a full path if dvipng is not in the executable search path. This option is only used when imgmath_image_format is set to 'png'.

imgmath_dvipng_args
Type:
Sequence[str]
Default:
('-gamma', '1.5', '-D', '110', '-bg', 'Transparent')

Additional arguments to give to dvipng, as a list. The default value makes the image a bit darker and larger than it is by default (this compensates somewhat for the thinness of default LaTeX math fonts), and produces PNGs with a transparent background. This option is used only when imgmath_image_format is 'png'.

imgmath_dvisvgm
Type:
str
Default:
'dvisvgm'

The command name to invoke dvisvgm. You may need to set this to a full path if dvisvgm is not in the executable search path. This option is only used when imgmath_image_format is 'svg'.

imgmath_dvisvgm_args
Type:
Sequence[str]
Default:
('--no-fonts',)

Additional arguments to give to dvisvgm, as a list. The default value means that dvisvgm will render glyphs as path elements (cf the dvisvgm FAQ). This option is used only when imgmath_image_format is 'svg'.

imgmath_embed
Type:
bool
Default:
False

If true, encode LaTeX output images within HTML files (base64 encoded) and do not save separate png/svg files to disk.

Adicionado na versão 5.2.

sphinx.ext.mathjax – Renderizado via math JavaScript

Aviso

A versão 4.0 altera a versão do MathJax usada para a versão 3. Pode ser necessário substituir mathjax_path por https://cdn.jsdelivr.net/npm/mathjax@2/MathJax.js?config=TeX-AMS-MML_HTMLorMML ou atualizar suas opções de configuração para a versão 3 (veja mathjax3_config).

Adicionado na versão 1.1.

Essa extensão usa math as-is nos arquivos HTML. O pacote JavaScript MathJax é carregado e transforma marcações LaTeX em math lidas na hora no navegador.

Como o MathJax (e as fontes necessárias) é muito grande, ele não é incluído no Sphinx, mas é configurado para incluí-lo automaticamente em um site de terceiros.

Atenção

Você deve usar as contas directive e role, não as nativas MathJax $$, \(, etc.

mathjax_path
Type:
str
Default:
'https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js'

O caminho para arquivo JavaScript incluído no arquivo HTML que chama MathJax.

O padrão é a URL https:// que carrega os arquivos JS a partir da rede de entrega de conteúdo (CDN) jsdelivr. Veja a página de primeiros passos com MathJax para detalhes. Se você deseja que o MathJax esteja disponível offline ou sem incluir recursos de um site de terceiros, é necessário fazer o download e definir esse valor para um caminho diferente.

O caminho pode ser absoluto ou relativo; se relativo, ele será em relação ao diretório _static onde foram construidos os documentos.

Por exemplo, se colocar MathJax no caminho estático dos documentos Sphinx, seu valor pode ser MathJax/MathJax.js. Caso seu host possua mais de um Sphinx definidos em um único servidor, é aconselhável usar um local compartilhado.

Você também pode fornecer uma URL https:// completa diferente da URL da CDN.

mathjax_options
Type:
dict[str, Any]
Default:
{}

As opções para rotular tag para o mathjax. Por exemplo, você pode definir a opção de integridade com a seguinte configuração:

mathjax_options = {
    'integrity': 'sha384-......',
}

Adicionado na versão 1.8.

Alterado na versão 4.4.1: Permitir alterar o método de carregamento (assíncrono ou adiado) do MathJax se a chave “async” ou “defer” estiver definida.

mathjax3_config
Type:
dict[str, Any] | None
Default:
None

As opções de configuração do MathJax v3 (que é usado por padrão). O dicionário fornecido é atribuído à variável JavaScript window.MathJax. Para obter mais informações, leia Configurando o MathJax.

Adicionado na versão 4.0.

mathjax2_config
Type:
dict[str, Any] | None
Default:
None

As opções de configuração do MathJax v2 ​​(que podem ser carregadas via mathjax_path). O valor é usado como parâmetro de MathJax.Hub.Config(). Para obter mais informações, leia Usando opções de configuração em linha.

Por exemplo:

mathjax2_config = {
    'extensions': ['tex2jax.js'],
    'jax': ['input/TeX', 'output/HTML-CSS'],
}

Adicionado na versão 4.0: mathjax_config foi renomeado para mathjax2_config.

mathjax_config
Type:
dict[str, Any] | None
Default:
None

Nome anterior de mathjax2_config.

Para obter ajuda para converter sua configuração antiga do MathJax para o novo mathjax3_config, consulte Convertendo sua configuração v2 para v3.

Adicionado na versão 1.8.

Alterado na versão 4.0: Isto foi renomeado para mathjax2_config. mathjax_config ainda é suportado para compatibilidade com versões anteriores.

sphinx.ext.jsmath – Renderiza math via JavaScript

Essa extensão trabalho como a extensão MathJax, mas usa antigo pacote jsMath. Permite valor de config:

jsmath_path
Type:
str
Default:
''

The path to the JavaScript file to include in the HTML files in order to load JSMath.

O caminho pode ser absoluto ou relativo; se relativo, ele será em relação ao diretório _static onde foram construidos os documentos.

Por exemplo, para colocar JSMAth no caminho estático dos documentos Sphinx, esse valor de ser jsMath/easy/load.js. Se em seu host há diversos conjuntos de Documentação Sphinx, é aconselhável instalar jsMath em local compartilhado.