Injecting arbitrary LaTeX code dynamically before \begin{document}

[yves-chevallier]

When writing a Sphinx extension or, even when using native Sphinx directives, some specific packages or commands must be declared ahead, before the \begin{document}. From my knowledge, it is currently impossible to dynamically add LaTeX code into the header from an extension or a directive.

A usecase is for exemple the hlist refactoring #8072. This proposal would use a new LaTeX environment \hlist that relies on several packages (multicol, regexpatch...). IMHO adding them directly in sphinx.sty isn't a good solution because you could add some unused packages if the user doesn't use any hlist in its documentation. The same would apply for many other case.

So I propose a way for extensions or even Sphinx directives to dynamically include some LaTeX code based on the usage.

My current way of doing it is the following:

latex_preamble = r"""
%% BEGIN injection for extension <% extension_name %>
\newenvironment{foobar}
<% somevalue %>
...
%% END injection for extension <% extension_name %>
"""

def inject_latex_header(app, context):
    render = LaTeXRenderer()
    context['preamble'] += render.render_string(latex_preamble, extension_context)

def inject_headers(app, doctree, fromdocname):
    if doctree.traverse(foobar) and hasattr(app.builder, 'context'):
        inject_latex_header(app, app.builder.context)

def setup(app):
    ...

    app.connect('doctree-resolved', inject_headers)

    ...

While this snippet works, I would prefer having a more convenient way of doing it with some guards that could perform some checks automatically. We could imagine a method such as:

app.add_latex_header(latex_code, context)

I am not sure though when this should be done. After the doctree is resolved?

[tk0miya]

Why do you need to insert "raw" LaTeX code to the preamble part? Why don't you create a .sty file (.cls file) and load it?

def create_mystyle(app, exception):
    if app.builder.name == 'latex' and exception is None:
        filename = path.join(app.outdir, 'mystyle.sty')
        with open(filename, 'w') as f:
            f.write(...)

def setup(app):
    app.connect('build-finished', create_mystyle)
    app.add_latex_package('mystyle')

[yves-chevallier]

There are two reasons behind this:

• The mystyle.sty you propose must be a template that must by rendered dynamically
• There are no reason to insert the .sty if the user do not use any of the new Directives added. This make the LaTeX build longer to build.

I would like to add the LaTeX extra code only if some nodes are inserted into the doctree.

[tk0miya]

Indeed. It seems the add_latex_package() has been evaluated at the initialization of LaTeX builder. I think it is better to delay the evaluation until just before writing. Then we can determine to add a LaTeX package on resolving phase.