Skip to content

Infra: Move templates to root of pep_theme directory - #5197

Closed
hwhsu1231 wants to merge 1 commit into
python:mainfrom
hwhsu1231-fork:infra/mv-templates-to-pep-theme-root-dir
Closed

hwhsu1231 wants to merge 1 commit into
python:mainfrom
hwhsu1231-fork:infra/mv-templates-to-pep-theme-root-dir

Conversation

@hwhsu1231

Copy link
Copy Markdown

This is a follow-up to #4404, closed on the grounds that the PEPs theme is internal-only and not intended to be overridden. That stands: this change is not about making the theme user-overridable. It is about the redundant configuration that using the theme's own templates through templates_path requires.

This PR moves the theme's Jinja templates from pep_theme/templates/ up to pep_theme/, drops the templates_path entry in peps/conf.py that existed only to point Sphinx at them, and also updates peps/docs/rendering_system.rst, which referred to the old template path.

Signed-off-by: Haowei Hsu <hwhsu1231@localizethedocs.org>
@hwhsu1231
hwhsu1231 requested review from a team and AA-Turner as code owners October 26, 2026 17:46
@python-cla-bot

python-cla-bot Bot commented Oct 26, 2026 •

Copy link
Copy Markdown

All commit authors signed the Contributor License Agreement.

CLA signed

@read-the-docs-community

Copy link
Copy Markdown

Documentation build overview

📚 pep-previews | 🛠️ Build #35420786 | 📁 Comparing 6673c42 against latest (227e111)

  🔍 Preview build  

1 file changed
± docs/rendering_system/index.html

@hugovk

hugovk commented Nov 8, 2026

Copy link
Copy Markdown
Member

What's the motivation for this change?

No user-facing changes, just to delete this line of config?

templates_path = [os.fspath(_PSE_PATH / "pep_theme" / "templates")]

This is the same as #4404, which was closed because:

I don't see any reason to do this, the PEPs theme is internal-only and not intended for overriding or etc.

What has changed since then?

@hwhsu1231

Copy link
Copy Markdown
Author

What's the motivation for this change?

No user-facing changes, just to delete this line of config?

templates_path = [os.fspath(_PSE_PATH / "pep_theme" / "templates")]

This is because the current configuration is redundant. We just need to place the Jinja templates directly under the theme directory (instead of inside an internal templates/ subdirectory):

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

Then, by simply specifying html_theme = 'pep_theme', Sphinx will automatically search for templates within the pep_sphinx_extensions/pep_theme/ directory. Therefore, there is no need at all to specify the location additionally through the templates_path configuration.

@hugovk

hugovk commented Nov 9, 2026

Copy link
Copy Markdown
Member

I don't mind much either way, but Adam wasn't keen last year and I don't see a new reason to change it now. Thanks anyway.

@hugovk hugovk closed this Nov 9, 2026
@hwhsu1231

Copy link
Copy Markdown
Author

@hugovk Actually, I'd rather ask: why did the maintenance team deliberately create a templates subdirectory inside pep_theme to store Jinja templates in the first place?

After all, even the built-in themes provided in the sphinx-doc/sphinx project demonstrate placing Jinja templates directly under the theme name directory. For example:

In addition, those well-known third-party themes also store Jinja templates following this convention. For example:

@hugovk

hugovk commented Nov 9, 2026

Copy link
Copy Markdown
Member

I don't know, but as mentioned, this theme is internal-only and not for re-use, unlike the seven mentioned.

@hwhsu1231

Copy link
Copy Markdown
Author

Even if it's not intended for external use, custom themes meant strictly for internal use basically also place Jinja templates directly under the theme name directory. For example:

Therefore, that's why I believe the current layout used by pep_theme is fundamentally incorrect. I still hope the peps team can reconsider accepting this PR.

@StanFromIreland

Copy link
Copy Markdown
Member

Is there any benefit for us, apart from being "like other projects"?

@hwhsu1231

Copy link
Copy Markdown
Author

@StanFromIreland

Is there any benefit for us, apart from being "like other projects"?

This is like wanting to calculate z = x + y;, but accidentally typing - instead of +:

z = x - y;

Normally, we would simply change - back to +. However, the current fix ends up being:

z = x - y;
z = z + y + y;

While the resulting value of z is correct, it is unnecessarily convoluted. Therefore, this PR simply aims to restore the clean and correct implementation of z = x + y;. So if you're asking what the benefit is, it's basically preventing buggy and redundant code from lingering in the codebase.

@hugovk

hugovk commented Nov 9, 2026

Copy link
Copy Markdown
Member

@hwhsu1231 I still don't see any new reason, or benefit other than dropping a line of config and being like other projects, so let's just drop this idea.

@hwhsu1231

Copy link
Copy Markdown
Author

@hugovk Just to be clear, I don't mean any offense by this, but could you please answer a question for me first?

As in the analogy I brought up in #5197 (comment), the current way Jinja templates are handled is essentially equivalent to writing z = x - y + y + y;. Don't you think this approach looks rather amateurish? You could simply get the desired value of z with x + y, yet you unnecessarily add a step of "subtracting y and then adding y back". Or do you genuinely consider z = x - y + y + y; to be an acceptable way to write it?

@hugovk

hugovk commented Nov 9, 2026

Copy link
Copy Markdown
Member

I think we've discussed this long enough, thanks.

@python python locked and limited conversation to collaborators Nov 9, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants