WIP: Added theming and dark mode support per #152.

[pm5k]

Abstract

As per https://github.com/pdoc3/pdoc/issues/152 -- added support for easy theming and dark-mode.

Changelog

• Created a themes folder inside of templates/ so there's a place for any number of user or maintainer-generated theme files.
• Created a default.mako theme alongside of a blank custom.mako theme. The user should probably use the custom file if they wish to add their own theme, or alternatively they can copy the default one, rename it and adjust settings therein.
• Moved all color defs from css.mako to default.mako so these can be built by the template renderer independently.
• 'css.mako' now only contains non-color styles and imports theme from 'default.mako' or whichever template the user specifies.
• Enabled automatic dark-mode switching based on user's system preference. This is handled by javascript inside of html.mako.
• Enabled switching modes using a button toggle on the docs themselves, which overrides system prefs.
• Enabled saving toggled theme state in local storage for convenience.
• Changed the hljs config parameter to now be a tuple of strings, where the first is light-mode and second is dark-mode, this gets loaded accordingly to the previously mentioned toggles to keep hljs blocks consistent with overall theme.
• Created "dark theme" based on Github's own dark mode. It now lives in default.mako.
• Widened .content as it was wasting real-estate.
• Adjusted hljs code blocks as the extra padding was not needed.
• Re-jigged media queries, as there's no need to split mobile/desktop. So I simply added one breakpoint for 1024.
• Set default "portables" breakpoint as 1024px, to better reflect modern-day screen sizes.

Demo from issue comment

[pm5k]

@kernc

Do let me know what your thoughts are regarding this. Additionally, following contribution guidelines, I ran flake8 and unittest, while flake8 came up with nothing, unit test had one failing test even before my change:

Traceback (most recent call last):
  File "/home/tom/pdoc/pdoc/test/__init__.py", line 100, in wrapper
    func(*args, **kwargs)
  File "/home/tom/pdoc/pdoc/test/__init__.py", line 1039, in test_Class_params
    self.assertEqual(pdoc.Class('G2', mod, G2).params(), ['*args', '**kwds'])
AssertionError: Lists differ: [] != ['*args', '**kwds']

Second list contains 2 additional elements.
First extra element 0:
'*args'

- []
+ ['*args', '**kwds']

Unsure if relevant, but thought I'd mention.

Would also be good to know if more changes are needed and get general feedback on this.

Thanks

[davfsa]

@pm5k Just wanted to drop in and say, amazing work. It looks splendid :heart: Thank you for working on this

[pm5k]

@davfsa

@pm5k Just wanted to drop in and say, amazing work. It looks splendid ❤️ Thank you for working on this

Thank you. I sort of left it here until I get a green light from someone. There’s a few changes to be made, but ultimately it would be nice to know whether there is a chance for this to get merged so I can just wrap this up. Of course it would also be good to get some critique from the author of the project as ultimately this would have to fit with their vision for pdoc. Glad you liked it though. :)

[sla-te]

If we set hljs_style_tuple = ('atom-one-dark', 'github'), we will get dark code highlighting and light pages - wanted to put dark mode to default and found that out.

[pm5k]

If we set hljs_style_tuple = ('atom-one-dark', 'github'), we will get dark code highlighting and light pages - wanted to put dark mode to default and found that out.

That’s purely because the first item is light and the second is dark. In order to set dark mode as default you would have to either swap the vars in the theme or I would have to expose that as an option. Right now it works in such a way that dark mode can only be set as default by toggling it once in the doc switch once rendered out. Good catch though. I will add it in at some point.