Re: [sphinx.ext.imgmath] Extend to content other than (exclusively) math?

[Denis Bitouzé]

Hi Hong,

Le 23/12/20 à 13h11, Hong Xu a écrit :

> On 12/23/20 10:08 AM, Denis Bitouzé wrote:
>
>> Hi Hong,
>>
>> I'm Denis, from France.
>>
>> As you can read here:
>>
>> ┌────
>> │ https://groups.google.com/g/sphinx-users/c/39glLBoRWHo
>> └────
>>
>> I wonder if it would be possible to extend sphinx.ext.imgmath to content
>> other than (exclusively) math. More precisely, I'd like to see
>> implemented a `.. latex::` directive more general than `.. math::` for
>> rendering arbitrary LaTeX content, preferably with dvisvgm for the
>> output.
>>
>> Unfortunately this is beyond my scope: I'm not sufficiently expert in
>> Python to extend sphinx.ext.imgmath properly.
>>
>> I see here:
>>
>> ┌────
>> │ https://www.sphinx-doc.org/fr/latest/authors.html
>> └────
>>
>> you add the svg support in imgmath extension and provide various bug
>> fixes, so you are much more able than me for such an extension.
>>
>> Do you think such an extension is easily achievable?
>
> I looked at the codebase again (which I haven't touched for more than
> 4 years), and I think it looks like the current functionality might
> satisfy what you need. Could you try:
>
> .. math::
>
> some non-math LaTeX stuff
>
> and let me know whether it works for you? If it does, all need to be
> done is to create a new directive that replicate this.

No, it doesn't work because imgmath switches automatically to the math
mode, I guess because of:

┌────
│ https://github.com/sphinx-doc/sphinx/blob/a18fee24f2b7f3507cfb02d56a48b107a78330e0/sphinx/ext/imgmath.py#L322
└────

and, maybe:

┌────
│ https://github.com/sphinx-doc/sphinx/blob/a18fee24f2b7f3507cfb02d56a48b107a78330e0/sphinx/ext/imgmath.py#L88
└────

> On a separate note, what is the motivation to have this feature?

See below.

> Because this isn't really a widely needed requirement, adding it to
> sphinx (if it happens at all) may get unsupported and buggy very
> soon.

I see. Very unfortunate :$ Is it the case for imgmath?

> If you would like to add svg converted from LaTeX, why not
> create a standalone LaTeX file and run dvi2svgm over them? You can
> create a small Python script for it and it's probably also much more
> flexible than having a Sphinx extension (given that it's very
> different from inserting math equations only):
>
> # gen.py
>
> import sys
> import pathlib
>
> s = """
> \documentclass[12pt]{article}
> \usepackage[utf8x]{inputenc}
> \pagestyle{empty}
> \begin{document}
> """ +
> pathlib.Path(sys.argv[1]).read_text() +
> """
> \end{document}
> """
>
> print(s)
>
>
> Then:
>
> # gen.sh
>
> python3 gen.py > doc.tex
> latex doc.tex
> dvisvgm -o doc.svg doc.tex

Nice, thanks! But see below.

The motivation of my request is a LaTeX FAQ (in French). It currently
exists as a DokuWiki site, which I don't like as a contributor and
that's the reason I try to export it as a Sphinx-doc site (as Gitlab
pages). This FAQ is currently in a very incomplete state (many questions
from a very old French FAQ that need to be updated, many questions from
the English FAQ not yet translated, etc.) and still needs a lot of work
(about 1000 questions) from potential contributors (I hope I could
convince many French folks to start to contribute). In the DokuWiki
site, thanks to the "LaTeX Plugin":

┌────
│ https://www.dokuwiki.org/plugin:latex
└────

LaTeX code snippets between the <latex> and </latex> tags are
automatically compiled and the resulting PDFs are converted as images
which added to the contributions when they are saved. The point is,
contributors of the Sphinx-doc site may want the same automatic
functionality without having to worry about Python to install and to
run.

> Feel free to CC the mailing list so that others can take advantage of
> our conversation in the future.

Done :)

Many thanks again!

Best.
--
Denis