multiple color themes? dark theme?
mgeier opened this issue · 10 comments
The mdBook project has a mechanism to select a color theme, see e.g. https://rust-lang.github.io/mdBook/.
It would be great to have a similar (of course optional) mechanism for the insipid theme.
I think the main difference to overcome is the code syntax highlighting. mdBook uses a JavaScript based solution (https://highlightjs.org/ if I'm not mistaken), while Sphinx uses https://pygments.org/ to generate the necessary CSS styles during the build process (without using JavaScript).
By default, Sphinx generates only one set of highlighting styles, but we would somehow have to generate multiple styles with Pygments, I guess.
This might need some Sphinx extension code, which would go kinda against my "back to the basics" goal mentioned in https://insipid-sphinx-theme.readthedocs.io/intro.html#goals. Therefore, I think it would be great to make the whole thing optional.
I recently discovered the Sphinx setting pygments_dark_style, which could be interesting (or not?), see https://www.sphinx-doc.org/en/master/development/theming.html#creating-themes.
See also sphinx-doc/sphinx#7101 and sphinx-doc/sphinx#7142.
The furo theme uses this uses something else which is confusingly also called pygments_dark_style (pradyunsg/furo#13, see also pradyunsg/furo#24).
Potential default dark styles for Pygments: monokai, native, inkpot (except for ugly highlighted lines), zenburn.
See also pygments/pygments#1526 for problems with tracebacks.
A Sphinx extension that adds a dark mode to the RTD theme: https://github.com/MrDogeBro/sphinx_rtd_dark_mode
Another site with support for dark mode: https://pillow.readthedocs.io/ (python-pillow/Pillow#4968)
And another one: https://docs.godotengine.org/en/stable/index.html
And another one: https://fasterthanli.me/
Another: https://rome.tools/blog/2022/02/08/rome-formatter-and-rust-update
And more:
https://www.c82.net/math-instruments/
A MkDocs theme with light/dark switch: https://squidfunk.github.io/mkdocs-material/getting-started/
I've also found an interesting Sphinx-based project which has a dark-theme-selector: https://proplot.readthedocs.io/.
Docusaurus also has a light/dark switch, e.g.
- https://oxidizer-rs.github.io/
- https://www.dimforge.com/
- https://tauri.studio/docs/getting-started/prerequisites
Discussions about dark mode (and draft implementation) for Python theme:
python/python-docs-theme#43
python/python-docs-theme#44
https://septatrix.github.io/cpython-dark-docs/
Discussions about sphinx_rtd_theme: readthedocs/sphinx_rtd_theme#224
pydata-sphinx-theme: pydata/pydata-sphinx-theme#273, pydata/pydata-sphinx-theme#458
CSS-only dark mode: https://dev.to/kleinfreund/css-only-dark-mode-3eg8
Pure CSS switcher: https://codepen.io/demilad/pen/bZRjpb
https://github.com/GoogleChromeLabs/dark-mode-toggle
https://paulmillr.com/posts/using-dark-mode-in-css/
https://alexandersandberg.com/articles/creating-a-website-theme-switcher-with-css-only/
More switcher examples: https://snarky.ca/, https://docs.soliditylang.org/
An overview article: https://css-tricks.com/a-complete-guide-to-dark-mode-on-the-web/
Another approach: https://chrismorgan.info/blog/dark-theme-implementation/
Any further suggestions?
Any volunteers?
I would like to see more difference between italic and literal font. The sphinx_rtd uses a different color for things in literal font.
When writing documentation I use italic font for variables that get replaced by the value and literal font for things that are as is. For example, the location were a python packages is installed might be denoted by:
*prefix*\ ``/lib/phthon``\ *version*\ ``/site-packages
where prefix is the install prefix and version is the version of python.
Here is an example of documentation that I am considering converting to use the insipid theme (instead of the rtd theme):
https://bradbell.github.io/cppad_py/doc/xsrst/cppad_py.html
This documentation uses the xsrst tool; see
https://bradbell.github.io/cppad_py/doc/xsrst/xsrst_py.html
a pseudo sphinx extension that I am developing.
Notice that, when using this tool, each page has its own table of contents at the top of the page and only the page titles are in the overall table of contents (each pages has a short and long title); see
https://bradbell.github.io/cppad_py/doc/xsrst/xsrst_automatic.html
I would like to see more difference between italic and literal font.
Sure, I'm open to that. Please provide a PR with a concrete suggestion.
I use italic font for variables that get replaced by the value and literal font for things that are as is.
Are you aware of the :file: role (https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-file)?
This seems to do exactly what you want in a less clumsy way.
We might be able to improve its styling, though.
each page has its own table of contents at the top of the page and only the page titles are in the overall table of contents (each pages has a short and long title)
And does that not work with the insipid theme?
If it doesn't work, please create a new issue, ideally with a minimal reproducible example.
How does one create a modified version of the insipid theme and test how it works ? I would need to be able to do this to create a pull request.
I use italic font for variables that get replaced by the value and literal font for things that are as is.
Are you aware of the
:file:role (https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-file)?
This seems to do exactly what you want in a less clumsy way.
We might be able to improve its styling, though.
I was not aware of the file role. It switches to italic for variables (a standard that comes form latex possibly tex). In the the rtd theme, it uses the same color for both the italic and normal text (red) and the difference does not stand out as much as I would like.
I use this for much more than just file names (and hence the name file for this purpose is missleading. For example, if array the name of a numpy array, I would use
:file:`{array}.shape`
One thing I am worried about using the file role is I do not seem to be able to escape the { character in the text; e.g.,
:file:`\{ {x}, {y} \}`
The surrounding braces and comma in normal font while x and y should be in italic.
I think I see how to test a modified version of the insipid themeL
-
Remove the currently installed version:
python3 -m pip uninstall insipid-sphinx-theme -
In the top directory of the modified insipid-sphinx-theme repo execute the command:
python3 setup.py install --prefix=$HOME/.local -
Then run sphinx using the insipid theme.
I am getting an error when I install insipid using a local copy of the current master:
pip uninstall insipid-sphinx-theme
python setup.py install --prefix="$HOME/.local"
If I then try to build my documentation using the insipid theme I get the error:
Running Sphinx v3.3.0
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 188 source files that are out of date
updating environment: [new config] 188 added, 0 changed, 0 removed
reading sources... [100%] xsrst/xsrst_py
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [ 0%] index
Theme error:
An error happened in rendering the page index.
Reason: TemplateNotFound('icons/search.svg')
If I do the following
pip uninstall insipid-sphinx-theme
pip install insipid-sphinx-theme --user
and then try to build my documentation using the insipid theme it works fine.
One thing I am worried about using the
filerole is I do not seem to be able to escape the{character in the text; e.g.,:file:`\{ {x}, {y} \}`The surrounding braces and comma in normal font while x and y should be in italic.
The :samp: role should work for this, but it does not seem to. I have posted a question about it on
https://groups.google.com/g/sphinx-users/c/v3sOTHVnpOg/m/1fAKG9R_AQAJ
How does one create a modified version of the insipid theme and test how it works ? I would need to be able to do this to create a pull request.
This is documented in detail in https://insipid-sphinx-theme.readthedocs.io/en/0.2.1/contributing.html#development-installation
If you need more information, please let me know.
I was not aware of the
filerole. It switches to italic for variables (a standard that comes form latex possibly tex). In the the rtd theme, it uses the same color for both the italic and normal text (red) and the difference does not stand out as much as I would like.
You can style this with CSS as much as you like.
If you have suggestions for the insipid theme, please let me know (ideally by creating a PR).
I recently discovered the Sphinx setting
pygments_dark_style, which could be interesting (or not?)
This is Furo-specific. Furo's dark mode support is honestly a horrible layer of hacks, that just so happen to be a stable set of hacks thanks to the amazing stability of Sphinx.
Thanks for checking this out!
This is Furo-specific.
There is definitely something in Sphinx that's called pygments_dark_style:
https://github.com/sphinx-doc/sphinx/search?q=pygments_dark_style
But maybe the one from Furo is a different thing with the same name?
I just assumed it would be the same thing ...
I don't know if that's possible, but I would like to be able to have a dark mode without needing any theme-specific Python code.
And maybe it might even work without JavaScript ...?
But maybe the one from Furo is a different thing with the same name?
It is.
Furo uses a completely different selector for the CSS and places all the styles into a single file. Sphinx uses multiple files, and puts the dark stuff under a separate CSS file that's activated with a media query; something that completely breaks the moment if the two pygments themes have any rule that isn't overlapping. :)