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

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.

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.

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.