Providing a template from a sphinx extension

[drewcassidy]

I'm writing a sphinx extension for version navigation, and would like to provide a sidebar widget template. Is there any way for an extension (not a theme) to provide an html template? As a workaround I have a global variable that end users can import and add in their conf.py, like so:

templates_path = [docput.sphinx_templates, "_templates"]

but it would be nice for this to not be necessary

[goutamadwant]

Yes. Add the extension's template directory during config-inited, which runs before the HTML builder initializes its template loader:

from pathlib import Path

TEMPLATES = Path(__file__).with_name("_templates")

def _add_templates(app, config):
    path = str(TEMPLATES)
    if path not in config.templates_path:
        config.templates_path.append(path)

def setup(app):
    app.connect("config-inited", _add_templates)
    return {
        "parallel_read_safe": True,
        "parallel_write_safe": True,
    }

Appending is preferable to prepending: a user's own _templates directory remains earlier in the search order and can override your packaged template. Include _templates/your_widget.html as package data in the wheel. Making the template discoverable is separate from deciding where it appears; the extension can document an html_sidebars entry or update that config deliberately in the same callback.