Dark color scheme

[jappi00]

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!

[kernc]

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!

[kernc]

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

[kernc]

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);
	}

[amaank404]

Hello, I was also looking for dark theme for pdoc3, can you please tell what fields am i supposed to modify in css file?

[kernc]

@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.

[amaank404]

So the thing I have ended up with is to copy the default css.mako and now i am going to make some changes to it so it looks good and dark. If i succeed, i will also submit a PR for seperate css.mako with commandline option changes for selecting inbuilt themes.

[amaank404]

Ok, so looks like I have pretty much achieved a dark theme. I tested that theme on pdoc documentation. but there are somethings like warnings, todo, notes, etc... that i have to change color of, so is there something like demo.py so i can test my theme on it and verify all the aspects of it.

Btw here is the progress by far (90% done):

Light theme (default):

Dark theme (in progress):

[kernc]

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.

[amaank404]

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.

that will be good if they use template-dir but what I meant is that --theme option could be added so the user could select inbuilt themes and the user can use --template-dir to override config of that inbuilt theme. basically theme option will also look for any packages installed that supply theme for pdoc (plugins).

In other words, --theme specifies inbuilt theme or python plugin theme and --template-dir specifies local overrides of the selected theme, by default --theme will be light. And as the collection grows more themes can be used with --theme option.

It's still up to you. I will still be happy to contribute my added themes.

Also, here is a alternative to --theme. We can format the input required by --template-dir, for example:

• Local theme: docs/themes
• Inbuilt or Plugin themes: theme:dark

Now in second case we can identify and resolve the path to the selected theme and I will be complete with dark theme by 3 days or most probably earlier.

[amaank404]

Looks like my theme is complete and ready for use, also it's more like black theme so i will also try making a greyish dark theme

[kernc]

@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.

[amaank404]

@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.

theme= will be great for me to add it up. And here is one more opinion because i see you really do not like to add up builtin themes and extra cli options. We can make use of plugins to extend themes. default for theme= will be light(inbuilt default), and we can use pypi package suffix pdoc-theme. Summarizing up: theme= option in config file; use of plugins for extending theme (I will submit my theme to pypi instead)

[amaank404]

By the way here is the almost final theme:

I changed scroll bar color and changed the color of code between back ticks. Also the location of the theme that i am working on is here

[amaank404]

so my last word is that i am gonna do nothing more than hosting a simple github repository with my template because the codebase is too complex for me.

[kernc]

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.

[amaank404]

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.

and yes that's what i did. so i guess i will soon host the repo for the dark theme. I have some work to do currently

[ghost]

Well here is another dark mode css.mako generated with coolors:

---

I do also have a suggestion: create a new repo pdoc3/pdoc-user-themes where pdoc users can submit their own themes. That way people can both get the themes they want while you do not have to make any changes to the existing code, all they have to do is add a link to their gist with a screenshot of the theme to the README.md. Win-Win.

[pm5k]

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.

[pm5k]

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

[Mylloon]

Hope your work will be merged soon 🙏

[tboerstad]

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

[amaank404]

As far as I am concerned, I do not think this is happening anytime soon, you can use my theme here if you would like to. You can copy the folder to where you run the commands and while generating the docs with the pdoc command just add this flag: --template-dir pdoc. I am not currently doing anything python related so this is all the help I can provide. For a preview look at this