Add Multi-theme support

[aftersomemath]

Adds multi-theme support using the new THEMES setting. You can specify all the themes that you will be using in python dictionary form. The keys to the themes can then be used by other themes to inherit.

This is still a work in progress, I have a couple things left to do including testing everything completely, a minor thing to prevent default settings from getting overwritten, and adding documentation.

I am just making a PR so that I can close the old one #1297. So much has changed that I feel the old PR needed to be closed completely.

[aftersomemath]

@mitchtbaum If you could give this a whirl and see if it works well for you that would be great! I want to get another opinion on if this was implemented properly.

[aftersomemath]

Documentation has been added and I have tested everything to make sure it works properly.

[naturallymitchell]

Thanks, @th3aftermath!! This works great.

@smartass101, thank you for explaining how to use prefixes to satisfy an explicit hierarchy. I fixed that in base and fixed_sidebar with these commits:

• https://github.com/mitchtbaum/base/commit/e223cde830292162b407e6038aced0be61fea125
• https://github.com/mitchtbaum/fixed_sidebar/commit/0e693721061c5fddb5ef1ad5c8e72a9e1deabfc1

To demo n-level inheritance, which this now allows, I made https://github.com/mitchtbaum/colored-fixed-sidebar, which only performs a single css override to change fixed_sidebar's appearance and pulls in all functionality from that theme and base.

There are some potential improvements that we can look into later. Let's do that afterward in #1092.

[smartass101]

I've rebased the PR in b00d9ef6d1e3bb580f1e2a3e36dcb65ce139cf9a. It seems to work well, @mitchtbaum confirmed. I think we can merge the rebased PR without much fear, it does not affect anyone not using this functionality. What do you say, @justinmayer, @avaris ?

[smartass101]

I agree with @kylef, implicit inheritance from other themes might solve the nuisance of having to prefix everything in the base theme as described in #1092, wouldn't you say, @mitchtbaum ?

It should be relatively easy to implement (it just mean looping over the lists), I can do it, the only real issue is how to make the responsible settings as convenient as possible.

My thoughts regarding that:

1. not sure if simple theme should remain as the hardcoded default. I think it should be the default, but not hardcoded.
2. as @kylef pointed out, the settings needs to represent order for implicit themes (so a tuple) and association for explicit inheritance (so a dict). Rather than making a combined syntax as @kylef wrote above, I propose having THEMES_IMPLICIT = ('simple', 'base') and THEMES_EXPLICIT = {'!base': 'base', '!simple': 'simple'} The docs would have to describe that THEMES_IMPLICIT merges the themes in a way and depends on the order.

However, I still get the feeling that having several implicit themes merged in such a way might have unexpected results. What I'd like to see is {% extend %} recognizing in which theme it is being called. Any ideas how to do that?

[smartass101]

I found a bug, fixed in 45945e6.

[smartass101]

After second thoughts and a look through the code I think I'll resort the the syntax proposed by @kylef as it is perhaps simpler to implement. Implemented in this commit b22f760. Bring on the comments :wink:

[smartass101]

another round of bugfixes: ad6b483

[smartass101]

I'm still having issues with getting the test to pass... tried to fix them in 5642f113679b6dc24db34e284383f2ed5729db29 but still not there, seems the simple theme is expected somewhere where I don't expect it. Any ideas?

[aftersomemath]

Maybe the 'THEMES' setting in test_settings.py is set incorrectly?

[smartass101]

thanks @th3aftermath, that seemed to be it :smile: , addressed in d71bae7

hmm, should I make another PR or still be reusing this one?

[honzajavorek]

I wish to have this feature. Let me know if there's something I can help with.

[naturallymitchell]

iirc, this patch needs refactoring to read ~PARENT_THEME from a metadata file within each theme, instead of in the templates themselves (Sphinx Docs and Nikola work this way). Then, Pelican could assemble its theme combo by reading each template from each theme in the themes dir and navigating within the theme directory to resolve missing templates referenced in each theme, based on its parent (similar to how simple theme currently works, only with multiple levels).

[honzajavorek]

@mitchtbaum Thanks for explanations and encouraging. I go skiing for several days, but then I'd like to solve this my issue https://github.com/honzajavorek/danube-delta/issues/4, so I'll really try to get to this.

Elsewhere you mentioned @smartass101's work in the add_multi_theme_support branch. With the one in this PR it's already two unfinished branches. What is the relation between them? The PR was first, was not finished, @smartass101 started to work on it in his separate branch, but also wasn't able to finish it?

I could try to resurrect this. When I look at all the comments and the code which was already written, I might have more questions, but now it's up to me to make the first move I guess. Thanks again for support.

[justinmayer]

Hi @honzajavorek. Any updates regarding your takeover of the work in this pull request?

[honzajavorek]

@justinmayer Unfortunately no, I temporarily overcame the limitation by having site.css with some specific CSS and colors linked after the main theme style. The file lives alongside content of each blog and overrides styles by CSS cascade. Examples:

• https://github.com/pyvec/blog.python.cz/
• https://github.com/honzajavorek/honzajavorek.cz

It has two downsides:

1. Changes in site.css are not being picked up by reloader, so when overriding my default style, I have to manually restart the pelican server and that's annoying.
2. It just doesn't feel right to have CSS files in the same folder as content.

However, having this half-working solution brought down my motivation to work on built-in support and I ended up dedicating time to different projects, such as PyCon CZ.

[boxydog]

Since this PR was created, someone merged a different inheritance scheme (THEME_TEMPLATE_OVERRIDES) in #2072, described in #2021.

I don't understand THEME_TEMPLATE_OVERRIDES and THEMES well enough to know how they should co-exist.