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

O formato da imagem de saída. O padrão é 'png'. Deve ser 'png' ou 'svg'. A imagem é produzida pela primeira execução de latex na marcação matemática TeX então (dependendo do formato requisitado) ou dvipng ou dvisvgm.

imgmath_use_preview

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

Padrão True. Se falso, não adicione código LaTeX com um atributo “alt” para imagens math.

imgmath_font_size

O tamanho do fonte (em pt) para math exibido. O padrão é 12. Deve ser um número positivo.

imgmath_latex

O nome do comando com o qual chamamos LaTeX. O padrão é 'latex'; pode ser necessário configurar o caminho completo, caso não esteja na variável 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

To use OpenType Math fonts with unicode-math, via a custom imgmath_latex_preamble, you can set imgmath_latex to 'dvilualatex', but must then set imgmath_image_format to 'svg'. Note: this has only been tested with dvisvgm 3.0.3. It significantly increases image production duration compared to using standard 'latex' with traditional TeX math fonts.

Dica

Some fancy LaTeX mark-up (an example was reported which used TikZ to add various decorations to the equation) require multiple runs of the LaTeX executable. To handle this, set this configuration setting to 'latexmk' (or a full path to it) as this Perl script reliably chooses dynamically how many latex runs are needed.

Alterado na versão 6.2.0: Using 'xelatex' (or a full path to it) is now supported. But you must then add '-no-pdf' to the imgmath_latex_args list of the command options. The 'svg' imgmath_image_format is required. Also, you may need the dvisvgm binary to be relatively recent (testing was done only with its 3.0.3 release).

Nota

Regarding the previous note, it is currently not supported to use latexmk with option -xelatex.

imgmath_latex_args

Argumentos adicionais passados para latex, como uma lista. O padrão é uma lista vazia.

imgmath_latex_preamble

Código LaTeX adicional para colocar no preâmbulo dos arquivos LaTeX usados para traduzir os trechos de math. Isso é deixado vazio por padrão. Use-o, por exemplo, para adicionar pacotes que modificam as fontes usadas para matemática, como '\\usepackage{newtxsf}' para fontes sans-serif ou '\\usepackage{fouriernc}' para fontes serif. Na verdade, as fontes matemáticas padrão do LaTeX têm glifos bastante finos que (na saída HTML) geralmente não combinam bem com a fonte do texto.

imgmath_dvipng

O nome do comando para invocar dvipng. O padrão é 'dvipng'; talvez seja necessário definir isso para um caminho completo se dvipng não estiver no caminho de pesquisa executável. Esta opção só é usada quando imgmath_image_format é definido como 'png'.

imgmath_dvipng_args

Argumentos adicionais para dar ao dvipng, como uma lista. O valor padrão é ['-gamma', '1.5', '-D', '110', '-bg', 'Transparent'], que torna a imagem um pouco mais escura e maior do que é por padrão (isso compensa um pouco a magreza das fontes matemáticas LaTeX padrão) e produz PNGs com um plano de fundo transparente. Esta opção é usada somente quando imgmath_image_format é 'png'.

imgmath_dvisvgm

O nome do comando para invocar dvisvgm. O padrão é 'dvisvgm'; talvez seja necessário definir isso para um caminho completo se dvisvgm não estiver no caminho de pesquisa executável. Esta opção é usada somente quando imgmath_image_format é 'svg'.

imgmath_dvisvgm_args

Argumentos adicionais para dar ao dvisvgm, como uma lista. O valor padrão é ['--no-fonts'], o que significa que dvisvgm irá renderizar os glifos como elementos de caminho (cf o dvisvgm FAQ). Esta opção é usada somente quando imgmath_image_format é 'svg'.

imgmath_embed

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

Version 4.0 changes the version of MathJax used to version 3. You may need to override mathjax_path to https://cdn.jsdelivr.net/npm/mathjax@2/MathJax.js?config=TeX-AMS-MML_HTMLorMML or update your configuration options for version 3 (see 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

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

The default is the https:// URL that loads the JS files from the jsdelivr Content Delivery Network. See the MathJax Getting Started page for details. If you want MathJax to be available offline or without including resources from a third-party site, you have to download it and set this value to a different path.

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

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-......',
}

O padrão é vazio ({}).

Adicionado na versão 1.8.

Alterado na versão 4.4.1: Allow to change the loading method (async or defer) of MathJax if “async” or “defer” key is set.

mathjax3_config

The configuration options for MathJax v3 (which is used by default). The given dictionary is assigned to the JavaScript variable window.MathJax. For more information, please read Configuring MathJax.

O padrão é vazio (não configurado).

Adicionado na versão 4.0.

mathjax2_config

The configuration options for MathJax v2 (which can be loaded via mathjax_path). The value is used as a parameter of MathJax.Hub.Config(). For more information, please read Using in-line configuration options.

Por exemplo:

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

O padrão é vazio (não configurado).

Adicionado na versão 4.0: mathjax_config has been renamed to mathjax2_config.

mathjax_config

Former name of mathjax2_config.

For help converting your old MathJax configuration to to the new mathjax3_config, see Converting Your v2 Configuration to v3.

Adicionado na versão 1.8.

Alterado na versão 4.0: This has been renamed to mathjax2_config. mathjax_config is still supported for backwards compatibility.

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

O caminho do arquivo JavaScript para incluir em arquivos HTML para carregar JSMath. Não há definição por padrão.

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.