Trimming the set of bundled-by-default themes

[pradyunsg]

At some point we should also evaluate the stable of default themes and if that needs a refresh, but I think the basic work is more pressing.

All bundled themes are not maintained well. So it might be time to unbundle.

Originally posted by @tk0miya in https://github.com/sphinx-doc/sphinx/issues/10646#issuecomment-1186106560

I'm filing this as a separate issue, so that we don't lose track of this idea. :)

[jdillard]

Here is the current list of bundled-by-default themes: https://github.com/sphinx-doc/sphinx/tree/master/sphinx/themes

What needs to happen for the list to be trimmed?

• Make a new repo (sphinx-contrib?)
• Make a pypi package (what maintainer?)
• Anything need to be done for the copyrights?
• Update the documentation.
• Move any issues related to the theme to the new theme repo

[12rambau]

I like the idea of unbundle them in sphinx-contrib and use them as any pipy package, @pradyunsg do you have a way to create minimal theme structur where we could simply copy/paste the layouts ?

[pradyunsg]

I've been meaning to create one for stb new but haven't done so.

https://sphinx-theme-builder.readthedocs.io/en/latest/filesystem-layout/ is the closest thing I have to that.

[pradyunsg]

I have extensive error reporting around the layout in sphinx-theme-builder, so I'd say create a rough pyproject.toml and resolve the errors as they pop up, and you'll have a functional layout.

[kaycebasques]

I have gone through this pain a couple times.

Presumably it's possible to split this work up into manageable chunks? Because it should be possible to transfer out themes one at a time. I can take on the work of migrating one out and documenting the process.

The only theme that should remain in the core repo is basic IMO, and it should be renamed to core to convey the idea that most 3P themes inherit from it / build on top of it. The fact that most themes build on top of basic could be a big asset to the Sphinx ecosystem in general because it provides an easy mechanism for shipping core features to most themes, such as the "skip to main content" a11y feature (#12407) I've been working on. Currently that sort of work is slowed down by having to update all these other old, built-in themes that probably have low usage in the wild.

[jdillard]

Since this is a breaking change, I think it needs to be decided on what major version it should happen in. The release plan for 8.0.0 is out and says:

This release would be only removing expired deprecations, dropping support for Python 3.9, and consequent refactorings -- I wouldn't expect any new features to be included.

I don't know if it is worth proposing adding in this work to 8.0.0 or deciding on doing it in 9.0.0.

[2bndy5]

Avoid circular dependency in pip

Any unbundled themes should avoid pinning to Sphinx before a certain version. Rather, unbundled themes should be allowed to install with whatever the current stable Sphinx supports.

I say this because a number of sphinx-contrib packages (required by sphinx) recently dropped support for sphinx v4 or earlier. So now, testing with sphinx v4 requires pinning to the sphinx-contrib dependencies that Sphinx v4 requires. See sphinx-immaterial/tests/requirements-sphinx4.txt as solution I use to protect tests from ~faulty~ undesirable pip behavior.

[jdillard]

I say this because a number of sphinx-contrib packages (required by sphinx)

The unbundled themes could be required as a stop gap measure (if it avoids making a breaking change and allows time for a deprecation message to be displayed), but eventually I think users that use those themes should be required to install them themselves.

[AA-Turner]

For now I don't want to unbundle -- doing releases is a real pain and having more opportunities to de-sync makes things even worse (c.f. the first-party sphinxcontrib-* packages).

Thanks all for thinking about this, but into torpor it now goes.

A

[2bndy5]

It isn't a bad idea though. In fact, I think its a "best practice" to parcel semi-related work into separate packages.

I can't argue with the release plan pains. I'm not sure if a monorepo would be helpful in that regard (about this issue). I think the release workflow (in general, not just in CI) could be automated better to the point where only pushing a tag is needed from a developer (then CHANGES.rst would be automatically amended and so forth).

[jdillard]

My intentions was to deprecate a lot of the old themes to make it so there less to maintain in the end.

[2bndy5]

Personally, I think it was a mistake to bundle any extensions and themes with sphinx at all. There wouldn't need to be as many releases if autodoc and others are maintained in a separate package.

To that end, I think the domains should be abstracted as well: Refactor sphinx into a simple (yet extensible) wrapper around docutils.