Current Setup

Currently, PEPs uses Sphinx's templating feature by:

1. Placing the required .html template files in the pep_sphinx_extensions/pep_theme/templates directory.
2. Specifying the pep_sphinx_extensions/pep_theme/templates directory via the templates_path configuration in conf.py.

My Suggestion

I suggest that PEPs make the following refactoring:

1. Move the template files under the current templates directory to the pep_sphinx_extensions/pep_theme directory.
2. Clear or remove the templates_path configuration in conf.py.

Rationale

According to the Templating section in the Sphinx documentation:

What is important to keep in mind is the order in which Sphinx searches for templates:

• First, in the user’s templates_path directories.
• Then, in the selected theme.
• Then, in its base theme, its base’s base theme, etc.

Since PEPs already specified html_theme in conf.py:

html_theme = "pep_theme"

This means Sphinx will look for template files in the theme directory (pep_sphinx_extensions/pep_theme) right after searching the directories listed in templates_path. Therefore, if those templates are placed directly under the pep_theme directory, like this:

pep_sphinx_extensions/
    pep_theme/
        partials/
            icon.html
        page.html
        theme.conf

Then there is actually no need to specify the templates_path directory in conf.py!

Similar cases:

• Sphinx13 Theme: _themes/sphinx13
• Conan Theme: _themes/conan_theme

Why Suggest This Refactor?

Although the current configuration used by PEPs works fine during the build, I recommend this change for two reasons:

On the one hand, the current setup is redundant.

On the other hand, and this is my main concern:

If PEPs hardcodes its templates_path value in conf.py, it prevents users from dynamically modifying the default templates of the PEPs theme via the command line using sphinx-build -D templates_path=<additional_path>. This is because such an argument will override the original templates_path value in conf.py.

For example, suppose that I want to include a .js file in page.html without modifying the existing page.html inside the pep_sphinx_theme directory. I could place my custom page.html elsewhere like the following:

Content:

{% extends "!page.html" %}

{% block extrahead %}
    <script type="text/javascript" src="{{ pathto('custom.js', 1) }}"></script>
{{ super() }}
{% endblock %}

Directory structure:

pep_sphinx_extensions/
    pep_theme/
        templates/
            partials/
                icon.html
            page.html
        theme.conf
peps/
    _templates/
        page.html   # Place my custom 'page.html' right here.
    contents.rst
    conf.py

Then, when running the sphinx-build command, I could specify -D templates_path=_templates to let Sphinx find my custom page.html.

However, because the -D templates_path=... command-line argument overrides the templates_path defined in conf.py, Sphinx can no longer find the original page.html from the theme directory, leading to an error when using {% extends "!page.html" %}:

sphinx.errors.ThemeError: An error happened in rendering the page api/index.

Reason: TemplateNotFound("'page.html' not found in
['/home/hwhsu1231/Repo/testing/peps/peps/_templates',
'/home/hwhsu1231/Repo/testing/peps/pep_sphinx_extensions/pep_theme']")