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

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

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

Padrão: False. Se for true, codifica imagens de saída LaTeX em arquivos HTML (codificados em base64) e não salva arquivos png/svg separados no disco.

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

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

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: Permitir alterar o método de carregamento (assíncrono ou adiado) do MathJax se a chave “async” ou “defer” estiver definida.

mathjax3_config

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.

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

Adicionado na versão 4.0.

mathjax2_config

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

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

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

mathjax_config

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

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.