Sphinx: Select Extensions on Build Type

[ax3l]

Following #1570, there is currently no way to easily control enabling or disabling a sphinx extension based on the build type in conf.py.

The concrete example I would like is building math via sphinx.ext.imgmath for epub but using sphinx.ext.mathjax for html. The rst macros/"interfaces" are compatible but the output is build-type specific.

This is also troublesome when building on RTD since one can not switch extensions on and off depending on the build type (but can build HTML, pdf and epub on RTD).

[tk0miya]

I think this contains two proposal. The first one is switching math extension for builders. The another is switching whole of extensions for builders.

I think the first proposal is understandable and easy to improve. Because math extensions (imgmath, jsmath and mathjax) are used only to represent equations on HTML builders. The common part of the extensions (nodes, directives, representations for other builders and so on) is implemented as a library module named sphinx.ext.mathbase. The difference of extensions are limited on writing phase. So it can be switched easily.

On the other hand, switching extensions by builders is hard. We have many types of extensions; builders, directives, transforms and so on. Some might work on reading phase, and some might on both reading and writing phase. But, in sphinx, the builder is determined at resolving phase.
http://www.sphinx-doc.org/en/stable/extdev/tutorial.html#build-phases

In addition, now we don't have to way to unload extensions.

Anyway, we have to consider the advantage of switching. If it is worthy enough, we should do it.

Any ideas?

[pashango2]

I have similar problems as well. However, my problem is not just formulas.

• sphinxcontrib-mermaid
• sphinxcontrib-plantuml
• sphinx.ext.graphviz
• etc, etc, etc ...

It is a common problem that all Sphinx extensions that generate diagrams have.
We need to control the output format with a lot of Sphinx extensions.

The easiest way is to pass the 'buildername' to the conf.py global variable. and leave the extension settings to the user.

Specifically, change here as follows.

Conf_globals = confoverrides or {}.
Conf_globals ['__ buildername__'] = buildername
Self.config = Config (confdir, CONFIG_FILENAME,
                      Conf_globals, self.tags)

This method is not elegant, but it is simple, easy and powerful.

[ax3l]

maybe exposing the builder in general to conf.py would be way to go here? would you like to prepare a PR for that?

[pashango2]

I'm sorry, I made a mistake in correcting it.
To be exact, modify 'sphinx/config.py' and 'sphinx/application.py'.

If sphinx can pass __buildername__ to the global variable ofconf.py, We can write as follows.

if __buildername__ == "epub":
    extensions += ['sphinx.ext.imgmath']
else:
    extensions += ['sphinx.ext.mathjax']

Prepare PR if necessary.

[tk0miya]

It is a common problem that all Sphinx extensions that generate diagrams have.
We need to control the output format with a lot of Sphinx extensions.

Hmm? Is that real problem of yours?
AFAIK the extensions you listed are incompatible for each other. so you can't switch one to another.
For example, sphinxcontrib-mermaid provides mermaid directive. But sphinxcontrib-plantuml does not. It uses plantuml directive to mark up UML diagrams. So you'll see errors even if sphinx support switching extensions.

The easiest way is to pass the 'buildername' to the conf.py global variable. and leave the extension settings to the user.

I'm worry about it breaks the incremental build feature of Sphinx. On the other hand, I still don't understand the advantages.
I understand about math extensions. So I'll hack them in 1.7.

[pashango2]

I apologize for being confused by my poor English ability.
The problem is simple.

Mermaid will output graphics in JavaScript as standard.
When outputting in HTML, output with JavaScript.
When outputting with Epub, output with Png.
I just want to do it.

I'd like to write like this in 'conf.py'.

extensions += ['sphinxcontrib.mermaid']

if __buildername__ == "epub":
    mermaid_output_format = "png"
    import os
    mermaid_cmd = os.path.abspath("../../node_modules/.bin/mermaid.cmd")
else:
    mermaid_output_format = "raw"

I also want to separate the output for each builder with other extensions.

appreciate the reply.

[wojdyr]

a workaround I'm using for this is checking sys.argv in conf.py. For example:

if 'epub' in sys.argv:
    # configuration for epub

[ax3l]

@tk0miya just a ping: did you add something for math extension switching to the 1.7 release and I missed it? :)

[tk0miya]

Sorry, nothing has changed yet because we determined to postpone this. New target release is 1.8.

[ax3l]

Ah sorry, I missed the modified milestone. Thanks for the heads-up!

[tk0miya]

I just finished migration of math notations to sphinx-core in #4988.
Since 1.8, you can switch math renderer module by *_html_renderer setting.

Thanks,

[ax3l]

This is great news, thank you! :sparkles: :rocket: