Dark color scheme

Hey,

I think we all love Darkmodes. What about pdoc? I think a default integrated Darkmode would be great! What do you think about something like this? Thank you for this awesome package!

We do. 😄

Integrated, but optional behind a config toggle, would indeed make sense. Or even something purely JS-based that shows a light switch on the client side for the user to switch at will. 🤔 💡

I won't be able to work on this shortly, so further discussion / PR welcome!

Or, if the way of a config tunable, a dict of preferred style colors would empower the user more. Something like:

# config.mako:

bright_color_theme = dict(foreground='black',
                          background='white',
                          link='...',
                          ...)
dark_color_theme = ...
color_theme = bright_color_theme  # Default

An even better idea is to provide a basic set of easily overridable colors in CSS variables (e.g. in pdoc/templates/colors.css) like it's currently for highlighting color:

pdoc/pdoc/templates/css.mako

Lines 6 to 8 in cd84fb3

    
             :root { 
        
               --highlight-color: #fe9; 
        
             }

pdoc/pdoc/templates/css.mako

Lines 184 to 186 in cd84fb3

    
                 dt:target .name { 
        
                   background: var(--highlight-color); 
        
                 }

@xcodz-dot

@xcodz-dot it's not available yet. There's just the idea to separate colors hard-coded all over css.mako into another file colors.css (or maybe theme.css), with CSS variables defined on the :root pseudo-class.

That new file then needs to be included in the html.mako template:

pdoc/pdoc/templates/html.mako

Lines 389 to 392 in aef1917

    
           <%namespace name="css" file="css.mako" /> 
        
           <style>${css.mobile()}</style> 
        
           <style media="screen and (min-width: 700px)">${css.desktop()}</style> 
        
           <style media="print">${css.print()}</style>

This sounds good enough in principle, but I think it's going to prove a breaking change for anyone who's customized their html.mako (but not css.mako). Maybe a safer alternative would be to declare all those color variables already in css.mako at the top, but then in html.mako conditionally load colors.css (if available) where interested users can put their individual color overrides. A standalone colors.css could serve as a standalone color template.
Or maybe the best would be to declare color variables in a separate colors.css, and then import it into css.mako/mobile section:

pdoc/pdoc/templates/css.mako

Lines 5 to 8 in aef1917

    
           <%def name="mobile()" filter="minify_css"> 
        
             :root { 
        
               --highlight-color: #fe9; 
        
             }

In either case, someone needs to figure it out, and I'd appreciate a PR.

pdoc.test.example_pkg tries out some features, including admonitions.

i will also submit a PR for seperate css.mako with commandline option changes for selecting

I'd rather first have a solid mechanism for customizing the color theme. We can bundle some themes after the feature spreads and matures. Till then, having the user provide --template-dir pointing to their overrides is the preferred approach.

@jappi00

@jappi00 It's likewise not as grave as you're having it. See #310. 😅

@xcodz-dot I'm not a huge fan of populous CLI switches that sooner or later nobody has proper count of (cf. pip, pytest). pdoc already uses a config file to tune template-related stuff, and it works via --template-dir and --config, so that'd be a theme= config setting. That said, I'm not sure I want to bundle a bunch of themes at the moment. For a start, I'd like to see a robust, backwards-compatible, extensible mechanism for color/style overriding. Only then, if the feature spreads (determined e.g. via GitHub search), we can bundle a few styles based on popular opinion. Since color and style are nearly wholly bikeshedding territory, I think this is the best approach.

Indeed, plugin support would be a heavy and questionably-worthwhile undertaking. At this stage still, extracting CSS colors into a separate overridable colors.css, as above, seems the most reasonable course of action.

From what I'm reading, it seems to me like this needs a little bit of fleshing out requirements-wise. I am tempted to give it a whack, but even if someone else decides to, might be nice to have these things listed in one space.

Edit: I am obligated to disclose that this is all selfish, as I am starting to introduce code-based self-documentation at work for our legacy Python projects, so this could go hand-in-hand with requirements I have thought up.

Edit #2: Decided to do some preliminary work around this, will do a PR once in a workable state. I still want to use this for myself, but in case this is good enough to act as a fully fledged theme support feature for pdoc that'd be even cooler.

Requirements

Support for dark mode, read more as this article does a pretty good job at explaining methods, tips and considerations for dark mode implementations.
Changes to be non-breaking, users who update to a release containing this code should not have their layouts break / look funny.
Override / Theming support - users should be free to modify CSS sources or override them to easily make their own custom themes for the entirety of the docs' "look and feel".

Considerations

Dark Mode support:

It seems like currently the CSS files are split up by "platform", I.E. mobile, desktop and print (although print is the odd one out here). I (personally) feel like there is no need for this at all, and the base style should just be one CSS file utilising an import of CSS vars (either from a preceding stylesheet or from the same one). I would also carefully re-group component-scope declarations in order to position them for the inevitable:

    :root {
        --bg-primary: #fff;
        --fc-primary: #000;
    }

    @media (prefers-color-scheme: dark) {
        :root {
            --bg-primary: #000;
            --fc-primary: #fff;
        }
    }

    body {
        background-color: var(--bg-primary);
        color: var(--fc-primary);
    }

What's great about this approach is that we can leverage mako to spit out these vars so we don't have to duplicate ourselves in writing them for :root and "dark-mode" :root, but more importantly it would make it incredibly easy to theme everything as well in a standardised way. For instance, a naive approach could be below. Do excuse the tab and newline mix in the code, I was hoping to see if this mattered (it did not), so the end result would be much cleaner and thankfully - easier to read.

css.mako

<%def name="make_colors()">
  <%
    # Name, default, dark mode
    css_colors = [
      ("--bg-primary", "#FFF", "#000"),
      ("--bc-primary", "#000", "#FFF")
    ]
    default = [f"\n\t{c[0]}: {c[1]};" for c in css_colors]
    dark = [f"\n\t\t{c[0]}: {c[2]};" for c in css_colors]

    vardef = (
      f"\n:root {{{ ''.join(default) }\n}}"
      + f"\n@media (prefers-color-scheme: dark) {{"
      + f"\n\t:root {{{ ''.join(dark) }\n}}"
      + f"\n}}"
    )
  %>
  ${ vardef }
</%def>

## Minify removed for output testing..
<%def name="desktop()">
  ${make_colors()}
...

Output

<style media="screen and (min-width: 700px)">
:root {
--bg-primary: #FFF;
--bc-primary: #000;
}
@media (prefers-color-scheme: dark) {
:root {
--bg-primary: #000;
--bc-primary: #FFF;
}
}
@media screen and (min-width: 700px) {
...

This means that these color variables could be config(or file)-driven allowing drop-in replacements for the sake of theming. Or you could have override files which Mako could diff between them and the default config to only apply variables that are included and leave un-overridden ones as default.

I think this could be a clean approach, albeit it would require a small rewrite to the css.mako file.

Non-breaking changes

Honestly, this it tough, because frankly if people are editing the css.mako file directly, there is little you can do to ensure continuous function of styles for such a change. In this scenario you're looking at a pre-release announcement with carefully detailed migration instructions for custom css.

For those who did not touch the css source, nothing changes. Any variations introduced in-html are frankly outside that context and are brittle by default. Say the use of inline styles - it's neither recommended (unless done via some automated and robust means) nor is it something that fosters compatibility. It's not necessarily easy for me to suggest people "suck it up" in this case, so maybe a note around moving custom components and styles out of templates and into the CSS file would be enough of a nudge.

Theming

With the change proposed/detailed above, I believe theming would become trivial. In-fact you could even provide a small pre-rendered "generator" SPA which would give users a nice UI around color changes which reflect how they will appear in the UI. Sort of like Bootstrap Magic, but incredibly scaled down for the purposes of function over form and small bundle size. It's just an idea, but would greatly extend support for theming.

In closing

I am unsure if I have missed any obvious points, but so far from what I have looked at, this could be a nice way to introduce dark mode and theming to PDOC, and hopefully not mess stuff up too much retroactively.

An update from my side - I have got a preliminary working dark mode and easier theming support (See gifs below for demo of this).

I retained all of the original styling of pdoc with the exception of content width, as it was wasting too much space by not filling all the space to the right of itself, and also the media queries as they were slightly cleaned up and the mobile/tablet/portable query was changed to breakpoint 1024 as this is what is defined as standard now for most responsive designs. This can be reverted if needed, however.

The color info was moved out of css.mako, but all the other css styles were retained.

Changes

The way I've implemented this is that it is driven via config.mako. The first change is that inside of this file you will see:

config.mako

## ...
hljs_style_tuple = ('github', 'atom-one-dark')  ## Replaces `hljs_style`
## ...
css_theme = 'default'

The hljs_style_tuple is there to support on-the-fly code highlighting swaps, so that if the user's system changes color mode preference or the user toggles this themselves, the documentation will adapt and not only swap between dark/light but also apply the same swap to HLJS. Therefore this value now has to have one style definition for light mode and one for dark mode.

The css_theme is literally there to tell mako which theme template to load. Each template has its own dark mode included by design. The default theme for instance is the vanilla pdoc3 theme when light mode is enabled and when switched to dark mode it adopts the dark theme of github's docs.

The template structure has changed thusly:

templates/
|__themes/
|     |__custom.mako
|     |__default.mako
|_ config.mako
|_ ...

Each theme is it's own file and contains the following structure:

default.mako

<%!
    from pdoc.html_helpers import minify_css
    colors = [
        ("--bg-highlight-color", "#FFEE99", "#3E4951"),
        ("--bg-default", "#FFFFFF", "#22282D"),
        ## ...
    ]

    default = [f"{color[0]}: {color[1]};" for color in colors]
    dark = [f"{color[0]}: {color[2]};" for color in colors]

    root_light = f":root[data-theme='theme-light'] {{{''.join(default)}}}"
    root_dark = f":root[data-theme='theme-dark'] {{{''.join(dark)}}}"
    root_light_auto = f"@media (prefers-color-scheme: light) {{ :root[data-theme='theme-light'] {{{''.join(default)}}} }}"
    root_dark_auto = f"@media (prefers-color-scheme: dark) {{ :root[data-theme='theme-dark'] {{{''.join(dark)}}} }}"

    color_variables = f"{root_light}{root_dark}{root_light_auto}{root_dark_auto}"
%>

<%def name="style()" filter="minify_css">
    ${color_variables}
</%def>

The css template also changed to now contain styling sans the color values and instead relies on the provided vars from the theme file. Which keeps the structure completely intact, but allows easy theming. All someone has to do is copy the default.mako and rename it, then change the color values, or fill in custom.mako to keep it as a private project theme.

Left to implement

~~Retain theme pref in localStorage.~~ LocalStorage now supported.
~~Finish color overrides for all relevant objects.~~
~~Clean up the code.~~

Demo

Hope your work will be merged soon 🙏

@pm5k

@pm5k Is dark mode still something that might show up? It looks great

Navigation Menu

Repository navigation

Dark color scheme #152

2 remaining items

Requirements

Considerations

Dark Mode support:

Non-breaking changes

Theming

In closing

Changes

Left to implement

Demo

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

	<%namespace name="css" file="css.mako" />
	<style>${css.mobile()}</style>
	<style media="screen and (min-width: 700px)">${css.desktop()}</style>
	<style media="print">${css.print()}</style>

	<%def name="mobile()" filter="minify_css">
	:root {
	--highlight-color: #fe9;
	}

Dark color scheme #152

Description

Activity

kernc commented on Jan 29, 2020

kernc commented on Jan 29, 2020

kernc commented on Aug 20, 2020

kernc commented on Feb 24, 2021

kernc commented on Feb 25, 2021

2 remaining items

kernc commented on Feb 25, 2021

jappi00 commented on Feb 26, 2021

kernc commented on Mar 1, 2021

pm5k commented on May 6, 2021

Requirements

Considerations

Dark Mode support:

Non-breaking changes

Theming

In closing

pm5k commented on May 12, 2021

Changes

Left to implement

Demo

Mylloon commented on Nov 19, 2021

tboerstad commented on Dec 22, 2022

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions