refactor site to use mkdocs sphinx

[vsoch]

This is the first PR (of likely a few!) to rebrand our documentation. This PR will only address changing the theme and overall style to use mkdocs jekyll, and I believe this is a good choice for a modern, searchable (and wide) look, and one that looks similar to other lab docs. This should build via sphinx as before, and here are some shots:

UPDATE the shots at the top here show sphinx-material - since this doesn't yet have support for light mode we are thinking of using sphinx-immaterial - see screenshots in this comment: #183 (comment)

Search works great!

Footer is nice too:

I got really excited when I saw these because I think they look great, however before I jump on what are next steps, I want to discuss this simple design. If folks like this design (and we merge) I'd like to follow up doing the following:

• proposal for re-organization of some sidebar content. E.g., there are multiple sections for job related things, these could be under a "Jobs" section and same for LLNL resource specific tutorials
• the opening page has a long list of links (which is good) but I think we would do better with welcoming page, links to most relevant sections, likely a graphic.
• I'd like to address comparison table needed front and center! #182 and get a comparison table up here.
• Features to add - code sections that are long can have accordian expanders, and I'd like to have easy "edit this page" buttons all over the site (so if a reader sees a bug they can quickly fix it)
• Adding typos checking CI (trust me, they are always there!)

After those major points, I can apply the same template to whatever projects are interested. I think to do this right we might even consider a shared flux framework sphinx template. I've never done this before, but how hard could it be!

Issues

• this will close overall docs format and branding #181

Signed-off-by: vsoch [email protected]

[garlick]

Nice!

I think I saw somebody mention the redundant TOC in left and right columns but I can't seem to find that comment now. I agree that it seems a bit odd to have that in two places.

I do miss the contrast of the background color in the notes and warnings boxes, e.g.

vs

In general the proposed format seems a bit bright and washed out to me now, but it could just be me!

Also, no big deal but we normally develop PRs in private forks per RFC 1 rather than pushing development branches to the main repo.

[vsoch]

The TOC are not redundant - the left is for the top level navigation and right is for the page.

[garlick]

The TOC are not redundant - the left is for the top level navigation and right is for the page.

Oh duh! Sorry.

[vsoch]

And the styles are Material Design and the colors match the defaults, e.g., that are also used where we use it: https://hpc.llnl.gov/cloud/services/MariaDB/

I can change them if you like, but it would look different than what someone usually expects for this design of site - let me know your preference!

[garlick]

I'll just throw it out there that I find the higher contrast look of the default RTD style to be a little more readable. Maybe it's just that there are fewer photons hitting my eyeballs since there are some darker areas.

I'm not trying to put the brakes on this, just giving my feedback which should not have a lot of weight given my total lack of graphic design fu. What do others think?

[vsoch]

oooh @garlick do we just need a dark mode? 🤔

[vsoch]

Say no more! Give me a few minutes to fumble around!

[vsoch]

okay so I found that this is underway! bashtage/sphinx-material#89 I could put together a custom solution, but I think we will be better off waiting for this release with sphinx-mkdocs and using it (vs doing the custom now and then needing to remove it). Would that be OK @garlick ? I can open an issue.

[cmoussa1]

I agree with @garlick that the site might benefit from using higher contrast colors, but like you suggested above @vsoch, a dark mode could definitely alleviate some of these concerns. :) I'm curious now if there are high-contrast color options that can be enabled that are separate from dark mode, however? Giving the option to enable both high-contrast and dark mode might improve general accessibility on the site. I don't mean to delay the good progress made on this PR already, though.

[vsoch]

@cmoussa1 I think these are really good questions and I'm going to open an issue so it's addressed at the root. They should be supporting these high contrast schemes, generally.

[garlick]

Works for me!

Did you see the reference to the immaterial fork? If it's a preview of what material might look like in dark mode, I like!

https://jbms.github.io/sphinx-immaterial/

[vsoch]

Yes! I think the work from that exact fork is that is referenced in the issue I posted. I suppose if we don't get that merged in time we could switch to that. I guess the question is - how long do you want to wait (e.g., not merging and making progress here waiting on a decision). I think some possible options:

1. Wait a short amount of time for an update on integrating dark mode, it could happen soon if it's done and we pinged
2. If that amount of time goes over, switch to sphinx-immaterial for the short term (and it has a dark mode)
3. Forget about waiting and I'll just switch to the theme now and we can switch back if sphinx-material gets dark mode?

I do think we should try to not delay on the overall Flux Docs work, so I'm leaning toward the last option. I don't mind watching it and doing another PR when the dark mode is available. The only reason to stick with sphinx-material is that it's more mainstream, but the other one could be just as good I think (knock on wood haven't tried it yet!)

Also I opened an issue about contrast bashtage/sphinx-material#129

[vsoch]

First shot - this looks nice so far! Looking for dark mode...

[garlick]

Could we schedule a 👍 👎 vote for the next project meeting after @grondo is back (1/19)? Or if we get people popping up here in the mean time and showing support, that would be good enough IMHO.

I really like the dark theme and if we're headed in that direction then I personally would vote yes to moving forward.

[vsoch]

OMG this is gorgeous! I'm losing my mind.

[vsoch]

Note:

1. top bar "lightbulb" switches between dark and light mode
2. top right "edit button" to edit the page on GitHub (something I wanted to add manually)
3. I found a mode to put all navigation in one bar on the left.

Everything (detail wise) is customizable - this is literally out of the box with a few theme customization tweaks. I think it's seriously beautiful and the dark mode is really nice!

The search is also much nicer looking

[vsoch]

Could we schedule a +1 -1 vote for the next project meeting after @grondo is back (1/19)? Or if we get people popping up here in the mean time and showing support, that would be good enough IMHO.

yep absolutely!!

Sorry for delayed response - my fire alarm went off AND my internet died in one fell swoop Mondays I guess? lol.

[garlick]

Ooh nice, where did the dark mode come from? I thought that was not yet available?

[vsoch]

Ooh nice, where did the dark mode come from? I thought that was not yet available?

This is sphinx-immaterial (not sphinx-material) which imho is much nicer is more ways than one. I think (as long as it remains fairly stable) we should even stick with it. See customizations https://jbms.github.io/sphinx-immaterial/customization.html

[grondo]

Great work and a huge improvement thanks! We can always make any design tweaks suggested by others in future PRs, so I say let's merge!

[vsoch]

okay I think this is good now - the old make check would run the spelling and that's replaced by spelling checks directly in the workflows file. The only improvement I'd make on there (which I'll do in a future PR) is to give that workflow a name instead of the filename.