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 delatex
na marcação matemática TeX então (dependendo do formato requisitado) ou dvipng ou dvisvgm.
- imgmath_use_preview¶
dvipng
edvisvgm
ambos têm a capacidade de coletar do LaTeX a profundidade da matemática renderizada: uma imagem inline deve usar essa profundidade em um estilovertical-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 comoTrue
.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 customimgmath_latex_preamble
, you can setimgmath_latex
to'dvilualatex'
, but must then setimgmath_image_format
to'svg'
. Note: this has only been tested withdvisvgm 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 theimgmath_latex_args
list of the command options. The'svg'
imgmath_image_format
is required. Also, you may need thedvisvgm
binary to be relatively recent (testing was done only with its3.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 fontessans-serif
ou'\\usepackage{fouriernc}'
para fontesserif
. 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 sedvipng
não estiver no caminho de pesquisa executável. Esta opção só é usada quandoimgmath_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 quandoimgmath_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 sedvisvgm
não estiver no caminho de pesquisa executável. Esta opção é usada somente quandoimgmath_image_format
é'svg'
.
- imgmath_dvisvgm_args¶
Argumentos adicionais para dar ao dvisvgm, como uma lista. O valor padrão é
['--no-fonts']
, o que significa quedvisvgm
irá renderizar os glifos como elementos de caminho (cf o dvisvgm FAQ). Esta opção é usada somente quandoimgmath_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.
- 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 ofMathJax.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 tomathjax2_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.