Add new default theme

[shimizukawa]

Dave Snider and Eric Holscher have graciously agreed to including a slightly altered version of the new RTD theme (which has a nicely responsive layout) as the new default for 1.3.

---

• Bitbucket: https://bitbucket.org/birkenfeld/sphinx/issue/1346
• Originally reported by: Georg Brandl
• Originally created at: 2014-01-14T09:25:36.987

[shimizukawa]

From ericholscher on 2014-01-14 08:29:02+00:00

+1 :)

[shimizukawa]

From ericholscher on 2014-01-14 08:29:55+00:00

Will this be included to replace the 'default' theme, or will we ship it as 'rtd' or something, and then just have the html_theme value default to that?

[shimizukawa]

From Georg Brandl on 2014-01-14 08:35:31+00:00

I think the second will be more backwards-compatibility friendly. Since sphinx-quickstart generates a not-commented-out "html_theme = 'default'", old docs will not suddenly change appearance, but for new docs quickstart will generate "default_new" or "rtd" or however it is called.

Teaches me not to ever call something that might change easily "default" :)

[shimizukawa]

From Takayuki Shimizukawa on 2014-08-06 12:16:31+00:00

+1, and I think the name "rtd" is better.

I want to include the (new default) theme to sphinx-1.3. What will be required in order to complete it?

[shimizukawa]

From ericholscher on 2014-08-07 00:07:46+00:00

I believe the theme doesn't support some of the options that Sphinx supports. We should go through and make sure the config options are added to the theme, so that users aren't confused when they update. The main issue is the concept of editable sidebars isn't used, since we have the TOCTree on that side.

I think it might be easier to include alabaster (https://github.com/bitprophet/alabaster) as the default, since it is a more "classical" Sphinx theme. I'd be up for discussing these issues though.

[shimizukawa]

From Georg Brandl on 2014-08-07 07:43:24+00:00

It's not necessary that all options are supported (such as left/right sidebar) if the theme doesn't silently replace the previous default one in existing projects.

The sidebars might be a problem though; I think that many people are using some kind of customization there.

[birkenfeld]

@ericholscher 1.3 is coming closer. I like alabaster and I have contacted Jeff about inclusion.

Still, I'm not happy that the default experience on RTD is so much different from that without.

[ericholscher]

Still, I'm not happy that the default experience on RTD is so much different from that without.

Can you expand a bit more on this?

I think Alabaster is a solid default -- it solves most of the issues with the old default, including having great mobile styles.

[birkenfeld]

Can you expand a bit more on this?

Hmm, it's hard to find words. Basically I mean that when you upload your docs to RTD, I think that without customization they should look similar to what you'd get with a local make html.

I think Alabaster is a solid default -- it solves most of the issues with the old default, including having great mobile styles.

Certainly true.

[ericholscher]

On Mon, Jan 19, 2015 at 11:18 AM, Georg Brandl notifications@github.com
wrote:

Can you expand a bit more on this?

Hmm, it's hard to find words. Basically I mean that when you upload your
docs to RTD, I think that without customization they should look similar to
what you'd get with a local make html.

Yea, this makes sense. We only do that on RTD when users have a theme set
to "default" -- the main reasoning here was that the "default" sphinx theme
was not great, and ours was generally better. If alabaster became the
default, we would have less reason to take over the default namespace.
Another way to work around this would be for 1.3+ to have the sphinx theme
set to "alabaster" -- which would make RTD not override it.

Eric Holscher
Maker of the internet residing in Portland, Or
http://ericholscher.com

[birkenfeld]

My plan would be to rename "default" to "classic", and to add "alabaster". When still set to "default", Sphinx would use "classic", but emit a notice and suggest to use alabaster. Quickstart would generate "html_theme = 'alabaster'".

[ericholscher]

Sounds like that would work around our logic pretty effectively. Then we
could let people explicitly opt-in to the "classic" theme by setting that
string, continue to override "default" with our own, and "alabaster" would
explicitly work like normal as well.

On Mon, Jan 19, 2015 at 11:25 AM, Georg Brandl notifications@github.com
wrote:

My plan would be to rename "default" to "classic", and to add "alabaster".
When still set to "default", Sphinx would use "classic", but emit a notice
and suggest to use alabaster. Quickstart would generate "html_theme =
'alabaster'".

—
Reply to this email directly or view it on GitHub
#1346 (comment).

Eric Holscher
Maker of the internet residing in Portland, Or
http://ericholscher.com

[birkenfeld]

Good news, @bitprophet is open to contributing the alabaster theme. But: I've just had another thought.

Why not keep the sphinx_rtd_theme and alabaster packages as is, and make them dependencies for installing Sphinx? Then you guys could keep updating the theme as you're used to, and in just one place. The theme would still be available for those using older Sphinx. The only thing that changes is that Sphinx would register their theme paths automatically, so that the changes to conf.py reduce to changing html_theme. And of course the Sphinx docs would feature these themes and explain the options/link to a page explaining them.

It would impose a kind of backwards compatibility restraint though. People would expect their projects to keep working and keep looking the same with themes available together with "vanilla" Sphinx.

There's also the question of packaging Sphinx up for distributions. For Gentoo, I can see that there are packages for quite a few popular themes, among them rtd, alabaster and bootstrap. Ubuntu has only alabaster, but it's probably easy for them to add rtd. It's probably similar for other distributions, since the themes are required to build documentation of packages that use them.

CC also to @ryan-roemer if he's interested in the same arrangement for the bootstrap theme.

[shimizukawa]

The only thing that changes is that Sphinx would register their theme paths automatically,

FYI. If external themes will have sphinx theme entry point in the setup.py, Sphinx does not require a change.

setup(
    ...
    entry_points="""
        [sphinx_themes]
        path = dotted.name.to.module:path_variable
    """,
)

[birkenfeld]

Yes, but: a) I don't trust entry points all that much and b) I want to "enforce" the dependency by importing the modules (probably in theming.py).

[shimizukawa]

Agreed 😃

[ryan-roemer]

I'm happy to help out with tweaks and such to sphinx-bootstrap-theme to help make it an option for a new sphinx installation.

Not sure how much this figures into the "separate vs. included" dep discussion, but the bootstrap theme is a bit unlike other Sphinx themes (read: more hacky) because we use a lot of runtime JS to finesse things into a BS2 or BS3 world. We have a long-running branch to do things the right way with HTML writing, but work on that branch has massively slowed down in the past few months.

[bitprophet]

Thanks for the Alabaster love, @ericholscher and @birkenfeld! :)

+1 on "just require the external packages" route, both as theme maintainer & Sphinx user (tho my main install case is just pip - the OS distro question is a good one).

There are a couple things I need/want to do to Alabaster before triggers are pulled on this, mostly some remaining major config options (such as fonts - just made bitprophet/alabaster#26) and tidying up project-level stuff (adding that entrypoint for Sphinx 1.2.x users; a real docs site with a changelog [meta!]).

I've a lot of other OSS priorities on my plate but depending on Sphinx 1.3's timetable (if any; I'm not on any MLs so no idea) I can make time at some point.

[birkenfeld]

Thanks for the feedback! I would suggest 1.3 final to be released around the end of February; I think one more beta is fine, which can already include the updated dependencies.

[keimlink]

When I switched my projects to Read the Docs Sphinx Theme I was confused by the html_sidebars option not being implemented. I ended up in "abusing" the versions.html template for my stuff.

@ericholscher Maybe you could extend the Read the Docs Sphinx Theme to allow a sidebar between the TOC and the versions.html template?

[ericholscher]

I have been scheming doing something along those lines. And adding an
ability to add custom links above the TOC as well ala
http://www.webhook.com/docs/

On Thu, Feb 12, 2015 at 5:28 PM, Markus Zapke-Gründemann <
notifications@github.com> wrote:

When I switched my projects to Read the Docs Sphinx Theme I was confused
by the html_sidebars option not being implemented. I ended up in
"abusing" the versions.html template for my stuff.

@ericholscher https://github.com/ericholscher Maybe you could extend
the Read the Docs Sphinx Theme to allow a sidebar between the TOC and the
versions.html template?

—
Reply to this email directly or view it on GitHub
#1346 (comment).

Eric Holscher
Maker of the internet residing in Portland, Or
http://ericholscher.com

[birkenfeld]

@shimizukawa can you please add the deps and change the default theme for the next beta? I'm sorry but I won't find time until then.

[shimizukawa]

@birkenfeld OK, I'll do it 😃

[shimizukawa]

Tasks for sphinx-1.3b3 (will be released at Feb 23):

• Rename 'default' theme to 'classic'.
  • rename themes/default to themes/classic
  • add new themes/default theme that derives from 'classic' theme for compatibility.
• sphinx-quickstart will generate html_theme = 'alabaster'.
• If user use 'default', sphinx emit notice (WARNING) suggestion to use 'alabaster' and use 'classic'
• setup.py depends to 'alabaster' and 'sphinx_rtd_theme' theme.
• theming.py import and run alabaster.get_path() to append path for alabaster theme.
• theming.py also import and run sphinx_rtd_theme.get_html_theme_path() to append path.
• add documentation for new alabaster and readthedoc theme and link to original pages:
  • https://pypi.python.org/pypi/alabaster
  • https://pypi.python.org/pypi/sphinx_rtd_theme

@ericholscher is URL for sphinx_rtd_theme correct? It seems that the PyPI page and updated date is far from github's one.

[shimizukawa]

@birkenfeld @ericholscher @bitprophet please check my commit 68021b0.

[birkenfeld]

Looks good, thanks. I made a small tweak to the warning message.

[birkenfeld]

@bitprophet we can haz font family setting now? ;)

[ericholscher]

Yes that is the proper place for our theme. We haven't rolled a release
from GH in a while. I'll plan on doing that.

On Mon, Feb 23, 2015 at 11:20 AM, Georg Brandl notifications@github.com
wrote:

@bitprophet https://github.com/bitprophet we can haz font family
setting now? ;)

—
Reply to this email directly or view it on GitHub
#1346 (comment).

Eric Holscher
Maker of the internet residing in Portland, Or
http://ericholscher.com

[shimizukawa]

@birkenfeld thanks for updating the message!
@ericholscher I got, thanks for sharing the information.

I'll release Sphinx-1.3b3 in 6 hours (JST's today :)

[shimizukawa]

1.3b3 has been released!

[bitprophet]

@birkenfeld Gah, yea I totally dropped that. Just merged your PR and will release unless I find something else that really needs to go in first - looking now.

[birkenfeld]

@bitprophet Thanks!

[bitprophet]

@birkenfeld saw already, but FTR I merged his PRs and released alabaster 0.7.x (probably should've just made it 1.0 but meh, next feature release :)).