sphinx-doc / sphinx-doc/sphinx

Allow loading themes as extensions without relaying on entry_point

Open
#9,729 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

type:enhancement
Dominant language
Python
Stars
8k
Forks
2.6k
PR merge metrics
No merged PRs in 30d

Description

Is your feature request related to a problem? Please describe.

I often use themes, but do not install them system or user wide as they are local to a project.
However, some themes require to be installed to be able to be used, more precisely they need a working (Python) entry_point. Pointing the PYTHONPATH to the correct location (like for normal extensions) is not sufficient in such cases.

Describe the solution you'd like
Therefore, I'd like to ask if it's possible to add a new config variable (or enhance existing mechanisms), call it theme_extensions which works like extensions but is only used/loaded, when the theme is initialized (e.g. around the point when sphinx.registry.Registry.load_external_theme() is executed).
This would provide an alternative way of registering themes as extensions besides entry_points.

Concept:

sphinx/theming.py
class HTMLThemeFactory:
    #...
    def create(self, name: str) -> Theme:
        for ext in self.app.config.theme_extensions:
            self.app.registry.load_extension(self.app, ext)
        #... no other changes

Describe alternatives you've considered

I tried (ab)using extensions preference, which works for some themes but not for others.
E.g. Furo does not work as it is loaded to early, or more precisely, it is loaded even if not a HTML builder is used.

I investigated whether I can load extensions in conf.py based on the builder being used but the builder information is not present at the time conf.py is executed.

I also tried using virtualenv for this, but this is error-prone since every time you need to build the project you have to remember to switch to the virtualenv. This also feels more like a temporary hack than a solution and is not portable to other systems in the sense that it is not a simple copy and paste of the project directory.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start in sphinx/theming.py at HTMLThemeFactory.create and compare it with sphinx.registry.Registry.load_external_theme(). Trace how app.config.extensions and theme initialization are handled, then identify the configuration and registration path needed for theme-only extensions. Done means a theme can load its local extension without relying on an entry point, while unrelated builders do not load it.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.