sphinx-material

sphinx-material copied to clipboard

It would be really neat if there was a configuration option to enable a dark mode (light text on a dark background). This would enable producing docs that looks like: https://fastapi.tiangolo.com/

Whenever I get around to updating to the latest Material for MkDocs this should be possible.

Happy to accept PRs that do the sync 👍

For reference, the dark theme scheme seems to be called slate and can be enabled in Material for MkDocs as shown here: https://squidfunk.github.io/mkdocs-material-insiders/setup/changing-the-colors/#color-palette-toggle

theme:
  palette:
    scheme: slate
...

The toggle at the top of the page will toggle slate on and off for their example application.

+1 I would be absolutely keen for this

If there is a CSS override I would also be keen to explore - I have opened #95 which proposes to explore this.

@johnthagen is this more of a general comment or is this something that can be enabled in the sphinx-material theme? The reason why I am asking is because if there is a way to enable it currently in a project using sphinx-material that would be really useful

@axsaucedo This is more of a general feature request that I think would be a really great addition to this project. I don't know how to enable this currently.

Once I sync with material mkdocs (hopefully in the next couple of months) this should become available.

This isn't in this project because slate wasn't a color in material mkdocs when I initially wrote the project.

I attempted to look into updating to sync in changes from material mkdocs. However, it isn't at all clear how to do that. Can you describe the process by which you derived this package from the mkdocs package?

I spent some time rebasing this package on mkdocs-material HEAD. I discarded the existing css and javascript since it isn't really in editable form anyway, and just used the original scss/typescript sources from mkdocs-material with only minimal modifications. I also kept the jinja html templates as close to the mkdocs ones as possible. That way keeping up to date with it in the future should be a lot easier. I have everything working about 90% now, including the dark theme support. I will send out a pull request shortly, once I've cleaned up the build scripts a bit more.

@jbms This sounds very exciting! Thanks!

@jbms This is more or less the way the original version came to be, so this makes sense. Looking forward to seeing and trying the PR.

@johnthagen @bashtage See pull request #96

Any update on this.

doesnt seem like it

@2bndy and I are now developing a fork of this theme (based on newer mkdocs-material), which includes dark mode, separately in https://github.com/jbms/sphinx-immaterial.

Once I sync with material mkdocs (hopefully in the next couple of months) this should become available.

Any news on this feature @bashtage?

Ping! Any updates here?

There's a fork with the desired option! https://github.com/jbms/sphinx-immaterial

Is there any reason you chose a fork instead of contributing upstream? The first reply in this thread suggested they would be welcome to accept a PR.

@ooliver1 well, for starters, jermanuts is only mentioning the fork, he's not the author of the fork, there's nothing bad with that. I, for myself, can not code in JS, but would like to include documentation with Sphinx in my Python projects instead. I would go for the fork.

Second, this project seems to be abandoned (no commits on the entire 2022). No answers from the developers whatsoever. Furthermore, if you go through the history of this issue thread, there's a PR (ignored for two years now), from the author of the fork, trying to contribute back in the days to this project.

When you get ignored that many times, forks arise. But there's no one to blame here, perhaps bashtage just got tired of maintaining this project, and that's OK. And obviously, the community got tired of waiting and took action, and that's OK too.

I don't think jermanuts deserves to be questioned, in public, for proposing the fork.

I would be happy to move the project on to someone who wants to work on it. I don't have the time or the inclination to maintain it, and especially to improve it. When I started it I took the material theme post rendering and so integrating changes like color variants was not easy.

As for the fork, it is OSS. Forking and improving is essential (precisely for cases like this, among other reasons).

If I can get statsmodels and my own repos to work well with immaterial, then I'll probably move to it in the next release and officially mothball this. If @jbms is interested in the name on PyPI, please get in touch.

I think at this point changing the sphinx-immaterial package name would just create confusion.

I agree, but just wanted to offer it in case.