tune-up

[2bndy5]

The PR I've been teasing about. This resolves #7 addresses #8 closes #9 and probably solves #6 too.
Huge thanks to @jbms for handy advice (despite my pestering)!

I've been posting the solutions in the corresponding issues' threads, so I won't go over that unless needed.

Notes

build.yml workflow

The CI workflow now accounts for linting python (with pylint latest) and checking python code format (with black latest). It now also tests Sphinx's latex builder and uploads artifacts of both html & latex built docs.

python linting

I did run black on all python sources in the sphinx_immaterial folder, and I added a .pylintrc file to tell pylint to ignore some common exceptions and all linting violations that are inherent with extending Sphinx builders.

Theme's docs

I urge you to visually check the docs currently hosted on my fork's gh-pages. I may have made some risque style choices, but my intention was to make these docs stick out from the other material themes' docs. The customization.rst page is where I heavily focused on because it describes all the great features this theme has to offer.

• I don't think the "new blocks" section is very relevant, but I didn't really test that info for accuracy.

Contributing guidelines

This should be improved... I just made a generic procedure for contributing (& possibly getting help). There are notes about what files to avoid changing, but I didn't specify the package*.json files in that list (I defer to @jbms expertise on that topic).

There is no stipulations about user behavior, but I think that's covered by the Github generic Code of Conduct. I hail from python's mentality in which "we're all adults here."

gh-pages

If completed successfully the CI workflow will upload the html docs to a gh-pages branch. This is currently done on every commit, but I left a comment in the yml to limit the gh-pages updates to release events only.

Please create a gh-pages branch in this repo before merging

[jbms]

It would be good to figure out a better way to handle icons, so that we don't have to rely on raw html and hard coding the svg icons into the html.

[2bndy5]

I could add a extra css for the docs, but I didn't want it used for all the pages. Also, I wanted the icons to change color with the different schemes. This was all I could find that would let me do that.

It is pretty annoying that the icons aren't copied with the theme's assets. (We're talking like less than 5 MB).

[2bndy5]

I also looked into using a icon font face but abandoned that when I realized the font face wasn't exactly like the svg assets in .icons sub-folders. Ultimately, I had to resort to the same tactic I outlined in #5

[2bndy5]

I've found this extension called sphinx-panels which adds custom roles for inline icons. Unfortunately, the material design icons aren't available. However, They are moving their code base to a newer extension called sphinx-design. I've raised an issue to see if inline material icon are on the horizon.

[jbms]

What is the use case for referencing icons directly in the rst? I see that in customization.rst they are used as examples for customizing this theme. It seems like they would more be useful for customizing admonitions, or defining new directives, rather than being used directly. Unfortunately pre-building the css makes it a bit tricky to change the icons properly, since they are inlined into the css. On the other hand, if the css isn't pre-built then some nodejs dependencies are needed when building documentation, which would also be unfortunate.

[2bndy5]

Instead of just showing the names of the icons, I wanted to show the icon itself (next to the icon's name). A picture speaks a thousand words...

Yes, I would like an easier way to customize the admonitions' icon. Sphinx also has a generic admonition that can be used to add new user-defined admonitions, but for some reason this theme treats generic admonitions like a .. note::.

I can imagine that some users might want to put them in the section headers (hopefully resulting in a icon in the nav menu items also).

[2bndy5]

Unfortunately pre-building the css makes it a bit tricky to change the icons properly, since they are inlined into the css. On the other hand, if the css isn't pre-built then some nodejs dependencies are needed when building documentation, which would also be unfortunate.

This is why I started looking at extensions that might do this already (less complications means less maintenance).

[2bndy5]

Would something like libsass python c-extension be helpful? I'm much more versatile with python than js.

I know python std lib comes with an xml parser, we could probably use to get the svg data into scss. I don't know much about scss either 🤣

[jbms]

Yeah, though unfortunately libsass is deprecated --- I don't think it supports all of the sass syntax used by mkdocs-material, though I could be mistaken. The recommended replacement is dart sass, but I don't think there are Python bindings for that.

[2bndy5]

damn I didn't see that warning. I wouldn't go the dart sass when the js implementation would be less complicated. I'll double my efforts in getting a material font face(s) as it seems more sustainable for our use case.

[jbms]

Thanks for putting this together!

[jbms]

One thing that would be very nice is if there were a way to get a live preview of the docs in pull requests. Unfortunately github actions artifacts don't let you actually view the html without first downloading it locally. But potentially some other free service could be used.

[2bndy5]

if there were a way to get a live preview of the docs in pull requests.

RTD can do this by checking a box in the project settings. But you should be the one to set this repo up on RTD (it's surprisingly easy).

[jbms]

Not sure if you are continuously updating your gh-pages site, but I noticed that in dark mode the primary color does not have good contrast against the background color.

Also the icons in the customization page don't display for me --- they just display as white squares.

[2bndy5]

I am keeping the gh-pages updated per commit. I didn't really like the accent primary color (I think its purple or deep-purple). Is that what you're referring to? Or are you talking about the header color (which is set to indigo)?

I did test changing the slate scheme's hue value in an overridden css rule... We could try that as a demonstration, but it might be misleading to users about the default value (232 I think). I really like how the mkdocs-material site allows temporarily changing the primary and accent colors dynamically, but I didn't look into that much.

[jbms]

I mean the primary color of indigo. It works fine as a header color, but when used as a text color I find it rather hard to read due to the low contrast.

[2bndy5]

Also the icons in the customization page don't display for me --- they just display as white squares

That seems odd. IDK what to say to that. I use firefox, and it displays fine for me (from gh-pages).

What primary color do you desire?

[2bndy5]

Ah. This may be a styling issue with chrome

It likely needs a chrome-specific mask-image attribute

[jbms]

As far as the color, I don't have any strong preferences, just that I would prefer higher contrast. I can read the text as is, but it is more difficult than I would like (perhaps a limitation of my eyes).

My understanding is that with the way receptors in the eye work, blue text on a dark background tends to be hard to read.

This is what I used for the tensorstore docs:

            'scheme': 'slate',
            'primary': 'green',
            'accent': 'light blue',

I found when playing around with the colors that with the way the mkdocs-material colors are set up, there aren't that many combinations that provide reasonable contrast for dark mode, unfortunately, and especially it is tricky if you want some consistency between light and dark mode.

I guess with the additional constraint that you wanted to avoid using the same colors as mkdocs-material, there aren't that many available options.

[2bndy5]

I'll play around with it. Yes, I'd like to avoid looking identical to the mkdocs-material site. If possible I'd like to avoid looking like sphinx-material site (though that doesn't seem difficult 😆).

I also chose green for my project's docs. So it may become the preferred color. As you pointed out: it is in the "eye of the beholder" at the end of it all.

[2bndy5]

ok I abstracted the custom css into its own file and added some -webkit-* attributes to account for chrome (and hopefully other browsers too). Also I went with deep-orange in the dark scheme's primary color with lime as its accent color. While I was at it I changed the light scheme's accent color to light-blue (teal looked kinda sickly). I also noticed the favicon wasn't displaying correctly in chrome, so I think I fixed that as well

[jbms]

Thanks! This brings us to a much better place. I have merged this PR since it is a helpful building block for other changes --- any followup changes can go into another PR.