Search code examples
pythonjinja2python-sphinxread-the-docs

How do I override a template on readthedocs?

I recently added sphinx documentation for blowdrycss to readthedocs.

I want to override the layout.html template on readthedocs. My current template override works fine on localhost, but not on readthedocs. The project uses the Alabaster theme which extends the basic theme.

Project directory structure can be seen here

The relevant parts are:

blowdrycss/
    docs/
        _templates/
            layout.html

        conf.py

Template setting in conf.py:

templates_path = ['_templates']

Contents of layout.html:

{% extends '!layout.html' %}


{% block sidebarsearch %}
    {{ super() }}
    <a href="https://flattr.com/submit/auto?user_id=nueverest&url=https%3A%2F%2Fgithub.com%2Fnueverest%2Fblowdrycss" target="_blank"><img src="http://button.flattr.com/flattr-badge-large.png" alt="Flattr this" title="Flattr this" border="0"></a>
{% endblock %}


{% block footer %}
    <div class="footer" style="text-align: center;">
        <a href="https://flattr.com/submit/auto?user_id=nueverest&url=https%3A%2F%2Fgithub.com%2Fnueverest%2Fblowdrycss" target="_blank"><img src="http://button.flattr.com/flattr-badge-large.png" alt="Flattr this" title="Flattr this" border="0"></a>
    </div>
    {{ super() }}
{% endblock %}

How do I override the layout.html template on readthedocs?

Update I've also tried:

The relevant parts are:

blowdrycss/
    docs/
        custom_templates/
            layout.html

        conf.py

Template setting in conf.py:

templates_path = ['custom_templates']
Solution

  • While readthedocs doesn't support the templates_path straight away, you can use a custom theme with templates inside of it. http://sphinx-doc.org/theming.html

    Simply create a new theme directory and add this to your conf.py:

    html_theme = 'your_theme'
html_theme_path = ['.']

    You can see an example in one of my projects: