2

I'm having some issues adding a custom footer to my Sphinx .html files. I'm using the sphinx_rtd_theme. I've checked this post and tried it (and some of the suggestions in the comments) but to no avail. I'm not sure what I'm missing. Apologies if I haven't posted enough here to actually indicate what is causing the problem. Any help or suggestions is appreciated!

My css theme file has been (poorly) modified by myself (I'm not an HTML/CSS person!) but I don't think that should matter? The only other thing I can think of is maybe I have to do something special when I re-compile the output files. I just use:

make clean html && make html

My conf.py is located at: root/source/conf.py. Here's some excerpts from my conf.py file:

import sphinx_rtd_theme

project = 'Project Name'
copyright = '2021, My Company'
author = 'My Name, Coworker Name'
master_doc = 'Home'
extensions = ["sphinx_rtd_theme", "sphinx.ext.todo"]
todo_include_todos = True
templates_path = ['_templates']
source_suffix = ['.rst']
html4_writer = True
html_theme = 'sphinx_rtd_theme'
# html_theme_path = ['_static']
html_static_path = ['_static']
# html_extra_path = []
html_show_sphinx = True
html_show_copyright = True
html_style = 'css/my_theme.css'

Here's my layout.html file that I have overridden. It's located in the path shown in the comment.

 <!-- layout.html
 * Place this file in root/source/_templates
 * -->
{% extends "!layout.html" %}
{% block extrahead %}
    {{super}}
    <link href="{{ pathto("_static/my_theme.css", True) }}" rel="stylesheet" type="text/css">
{% endblock %}

{% block extrafooter %}
    {{super}}
    <div class="footer">
        My custom footer just needs to add a single sentance to the existing footer.
    </div>
{% endblock %}
mzjn
  • 48,958
  • 13
  • 128
  • 248
als0052
  • 388
  • 3
  • 13
  • @LexLi I'm not building an entire new template... I'm trying to add a single line to an existing part of the existing template. – als0052 Apr 02 '21 at 16:57
  • You need the same level of expertise on HTML/JavaScript/CSS to customize a few lines even if not the full theme. – Lex Li Apr 02 '21 at 17:53
  • 1
    sphinx_rtd_theme is a separate package from Sphinx and its default themes, so this technique needs modification. Its [configuration options](https://sphinx-rtd-theme.readthedocs.io/en/latest/configuring.html) out of the box is limited. You can fork the package and modify the theme templates. I don't know of any other way to extend its templates, but there is an [open issue](https://github.com/readthedocs/sphinx_rtd_theme/issues/582). – Steve Piercy Apr 03 '21 at 10:19

2 Answers2

6

Do you want to add a custom footer or replace the default one? in my case, I only need to override the footer.html file instead of layout.html.

Here's what I do that 100% worked for my Sphinx documentation:

  1. create a footer.html in the _template folder of your Sphinx project.
  2. then add this:
{% extends "!footer.html" %}
{%- block contentinfo %}
{{ super }}
<!-- your custom footer here-->
{% endblock %}

be mindful in which block your footer is actually contained within. In my case it's inside contentinfo

Crispy-Broccoli
  • 61
  • 1
  • 3
  • Yep that's also what I did. See below for my solution. The curly braces initially threw me off when I was trying to add my content to the footer.html but trial and error eventually solved it if i remember correctly. Been a while. Do you know of any other way to do this or is modifying the footer.html file the only way to add custom footer content? – als0052 Jan 20 '22 at 11:22
  • Yep, I think you can use the (% extrafooter %} block too . If you want to add new content while still maintaining original content from your default footer, maybe don't leave out the {{ super }} statement too? – Crispy-Broccoli Jan 21 '22 at 15:13
2

So I found a workaround.

1. Copy existing RTD html files

I copied the existing RTD .html files from my virtual environment folder. On my system it was located at the usual place:

.../Miniconda3/envs/my_env_name/Lib/site-packages/sphinx_rtd_theme/

I found the following files:

  • breadcrumbs.html
  • footer.html
  • Layout.html
  • search.html
  • searchbox.html
  • theme.conf
  • versions.html

I copied those to my working directory for my project:

.../Documentation-repo/Sphinx/root/source/_templates/

2. Edit conf.py file in working directory

I opened my conf.py file and changed the following:

# Add any paths that contain templates here, relative to this directory.
#   Uncomment the line below to enable customized template #
#
# templates_path = ['_templates']

to this:

# Add any paths that contain templates here, relative to this directory.
#   Uncomment the line below to enable customized template #
#
templates_path = ['_templates']

3. Add new content to footer.html file

I opened footer.html and edited it to add the content I wanted at the bottom. In my case it was as simple as adding my single sentence of changes below the {%- block extrafooter %} {% endblock %} line. Easy. Might not be the perfect solution but it works for what I need.

als0052
  • 388
  • 3
  • 13