sphinx-doc / sphinx-doc/sphinx
Allow loading themes as extensions without relaying on entry_point
Nobody has claimed this yet.
- 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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