Update Sphinx theme re move to latest bootstrap #493

[phillxnet]

Fixes #493

This pull request's proposal

Update our Sphinx bootstrap based theme dependencies; avoiding our contributors having to wade back through historical references for proposed fixes.

Includes:

• Removal of redundant jslibs & css files.

---

In updating from a now very old bootstrap of v3.3.4/5, to v5.3.3, we have a number of breakages.

Checklist

• [ ] With the proposed changes no Sphinx errors or warnings are generated.
• [ ] I have added my name to the AUTHORS file, if required (descending alphabetical order).

[phillxnet]

@FroggyFlox & @Hooverdan96 I'm a little at a loss currently on this one. Although this draft PR branch does now fix the indicated issue (small screen navbar function), I'm seeing the following almost illegible text in some places.

E.g. (when using a loopback server as per our docs): http://0.0.0.0:8000/installation/quickstart.html

Compared with our current PRODUCTION master branch which displays the same area just fine:

With this branch, some overrides have been removed, but I think the miriad changes in bootstrap have again foiled our efforts here. Any ideas, I know we've seen the like of this a while back.

Just wanted to get the bootstrap updated fully, as we will be doing the same in the Web-UI (next testing channel) as-well, so should server to help with that effort also.

[Hooverdan96]

When you check a page like /interface/overview.rst do you also see the same behavior? I am wondering whether the text qualifier might be at fault after the code-block directive in the page you've sampled. Or is it in other ones, too, if you checked? In the sphinx documentation that is not a valid option, though it could be in the referenced pygment lexer aliases.

[FroggyFlox]

I think you're into it here, @Hooverdan96 ... That indeed reminds me we had that issue a while ago where a lot of our text/code was showing as barely visible and I do believe this is how we fixed it then... Not sure why there are still some of that if that is the case, though.

[phillxnet]

@Hooverdan96 Re:

When you check a page like /interface/overview.rst do you also see the same behavior?

Yes, it is the same with all our .. code-block:: console highlight blocks. Pretty sure this is an interplay with Sphinx theme/highlight Pygments (https://www.florian-diesch.de/doc/sphinx/themes-and-pygments-styles/index.html#theme-sphinxdoc) and new bootstrap doing yet more overrides etc via _root.scss and _reboot.scss. I've yet to get familiar with these as it goes.

I think what we need is far less override layers !!! So we don't keep getting tripped up every time we update anything here.

[phillxnet]

OK, some progress, in our own theme we had a disabled override:

https://github.com/rockstor/rockstor-doc/blob/cb5651b80708453d03731b2cb626649ffc22d95d/themes/rockstor/static/css/syntax.css#L8

re-instating, now we seem to have lost some works-by-accident arrangement we had previously via Sphinx bootstrap highlight on console highlight !!

 .highlight { background: #272822; color: #f8f8f2 }

And we have:

Bit harsh but at least it's narrowed down a tad. I'll look to see if we can remove this override entirely as I suspect is was grabbed from some auto-generated theme that may now no-longer apply. Especially give we now have bootstrap doing different overrides now.

[phillxnet]

Our most recent linkcheck fail:

(interface/overview: line  214) timeout   https://teamspeak.com/en/ - HTTPSConnectionPool(host='teamspeak.com', port=443): Read timed out. (read timeout=20)
455

But the site now looks to be good when visited using a browser!

[Hooverdan96]

Not that I have understood all that much, but there now seems to be a more simplified/elegant way to manage overrides that came with bootstrap 4, but I let you figure out what that really means :):

https://getbootstrap.com/docs/5.3/customize/overview/

[phillxnet]

@Hooverdan96 Thanks. I did notice a number of significant changes re CSS etc, and this was all part of the problem: yet more layers. And we definitely have some more simplifications & modernisations that we can work on here.

From your link the following looks to pertinent: https://getbootstrap.com/docs/5.3/customize/css-variables/

I am keen to reduce our Sphinx theme to a minimum, but at least in this phase we fixed the collapsed bar fail and did-away with a number of older js libs. So bit-by-bit. In time we can fully modernise / minimise our remaining overrides to hopefully ease future development here. We do have a similar update lined up for the Rockstor Web-UI in our next testing phase. So all good re gaining recent familiarity.