Bad CSS in documentation section

[aaronsgiles]

I noticed that the locally-generated HTML for documentation shows up differently than the live docs on the mamedev.org site. For example, if you look at https://docs.mamedev.org/techspecs/luareference.html vs. what shows up when you build it locally, you’ll see this ugliness:

I looked into fixing this but the CSS checked into the mamedev.org is minified which makes it super annoying to sort out.

Looks like our ul/li rules are overriding the sphinx CSS ones. If I disable some of them it starts to look closer. For example, list-style:none is killing the bullets, and padding:0 is killing the indent. Seems like we apply these globally. Paragraph margin is adding lots of vertical space that shouldn't be there, but even killing that it's too spaced.

[aaronsgiles]

Ok, after some fiddling, if I add this to the bottom of the stylesheet, it fixes the TOC:

.simple { margin:0 0 24px 24px }
.simple ul { padding: 0 0 0 24px }
.simple li { list-style: disc outside none } 
.simple li li {list-style: circle outside none } 
.simple li li li {list-style: square outside none } 
.simple li > p { margin:0 }

(Edited to remove div.contents at the front as this CSS problem also affects bulleted lists within the main body as well.)

[aaronsgiles]

Ok, did some more investigation on the docs formatting.

First, the problems affect all lists in the docs, not just the ones in the TOC.

Second, it seems to be down to using <div class="section"> vs <section> tags.

When building locally, it emits <div class="section"> and it seems that the CSS is geared to key off of that.

However, whatever mechanism builds the docs online uses some option that causes the generator to emit <section> tags instead of <div class="section"> and when that happens, any CSS we had to key off of .section gets ignored.

[aaronsgiles]

So it seems the online building system is using either a newer Sphinx and/or a newer RTD theme.

I grabbed the CSS from the latest RTD theme and noticed that it included several relevant selectors that were previously missing.

I updated just the CSS in our docs folder and that seems to have been good enough to solve the problem.

Ideally we should make sure that whatever we're building within online matches what we're building with locally.

[aaronsgiles]

Looks like there was an issue reported for this problem. Sphinx 4+ emits

instead of

and this messes up the RTD CSS. Their suggested workarounds are to include a kludge CSS or use the latest version of the theme.

https://github.com/readthedocs/sphinx_rtd_theme/issues/1145

I don't see any problems with the 1.0.0rc1 version of the theme so I'm inclined to update to that. Or we can wait for the official 1.0 release, since we have the CSS workaround in place for now.

I've created a PR in the main tree to update the RTD theme to 1.0.0rc1. This is not a mamedev.org issue, so closing this.