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 directive e role do math do reStructuredText.

sphinx.ext.imgmath – Renderiza 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

Tipo:

'png' | 'svg'

Padrão:

'png'

O formato da imagem de saída. Deve ser 'png' ou 'svg'. A imagem é produzida executando-se primeiro o latex na marcação matemática TeX e, em seguida (dependendo do formato solicitado), o dvipng ou o dvisvgm.

imgmath_use_preview

Tipo:

bool

Padrão:

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

Tipo:

bool

Padrão:

True

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

imgmath_font_size

Tipo:

int

Padrão:

12

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

imgmath_latex

Tipo:

str

Padrão:

'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

Tipo:

Sequence[str]

Padrão:

()

Additional arguments to give to latex, as a list.

imgmath_latex_preamble

Tipo:

str

Padrão:

''

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

Tipo:

str

Padrão:

'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

Tipo:

Sequence[str]

Padrão:

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

Tipo:

str

Padrão:

'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

Tipo:

Sequence[str]

Padrão:

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

Tipo:

bool

Padrão:

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

Atenção

The default version of MathJax changed from version 2 to version 3 in Sphinx 4.0, and from version 3 to version 4 in Sphinx 9.0.

You may need to override mathjax_path to load an older version, or update your configuration options. In general, MathJax v3 and v4 options are compatible.

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.

Dica

MathJax configuration can be supplied in a JavaScript file by using the mathjax_config_path option. This is useful for more complex configurations that are hard to express only using a Python dictionary, for example JavaScript functions.

mathjax_path

Tipo:

str

Padrão:

'https://cdn.jsdelivr.net/npm/mathjax@4/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.

Alterado na versão 4.0: The default version of MathJax is now version 3. To keep using MathJax v2, you must explicitly load it via this option. For example:

mathjax_path = 'https://cdn.jsdelivr.net/npm/mathjax@2/MathJax.js?config=TeX-AMS-MML_HTMLorMML'

Alterado na versão 9.0: The default version of MathJax is now version 4. To keep using MathJax v3, you must explicitly load it via this option. For example:

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

mathjax_options

Tipo:

dict[str, Any]

Padrão:

{}

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.

mathjax4_config

Tipo:

dict[str, Any] | None

Padrão:

None

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

For help converting your old MathJax configuration to to the new mathjax4_config, see Converting your old Configuration to v4.

Adicionado na versão 9.0.

mathjax3_config

Tipo:

dict[str, Any] | None

Padrão:

None

The configuration options for MathJax v3 (which can be loaded via mathjax_path). If given, the dictionary is converted to a JSON object and assigned to the JavaScript variable window.MathJax.

For more information, please read Configuring MathJax.

Adicionado na versão 4.0.

mathjax2_config

Tipo:

dict[str, Any] | None

Padrão:

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

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 4.0: mathjax_config foi renomeado para mathjax2_config.

mathjax_config

Tipo:

dict[str, Any] | None

Padrão:

None

Nome anterior de mathjax2_config.

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.

mathjax_config_path

Tipo:

str

Padrão:

''

If given, this must be the path of a JavaScript (.js) file (path relative to the configuration directory) that contains the configuration options for MathJax. Example:

mathjax_config_path = 'mathjax-config.js'

Importante

The user is responsible for ensuring that the given file is compatible with the version of MathJax being used.

For more information, please read Configuring MathJax.

Adicionado na versão 9.0.

sphinxcontrib.jsmath – Render math via JavaScript

This extension works just as the MathJax extension does, but uses the older package jsMath. jsMath is no longer actively developed, but it has the advantage that the size of the JavaScript package is much smaller than MathJax.

Adicionado na versão 0.5: The sphinx.ext.jsmath extension.

Alterado na versão 2.0: sphinx.ext.jsmath was moved to sphinxcontrib.jsmath.

Removido na versão 4.0: The alias from sphinx.ext.jsmath to sphinxcontrib.jsmath.

Config value:

jsmath_path

Tipo:

str

Padrão:

''

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.

For example, if you put jsMath into the static path of the Sphinx docs, this value would be jsMath/easy/load.js. If you host more than one Sphinx documentation set on one server, it is advisable to install jsMath in a shared location.

Previous

sphinx.ext.linkcode - Adiciona links externos ao código-fonte

Next

sphinx.ext.napoleon – Suporte para doctrings de estilo NumPy e Google