[WIP] Static HTML output with Sphinx

[n8willis]

This is an attempt to make the document set buildable, locally, as static HTML pages, so that they can be easily used outside of the GitHub web interface.

Obviously there are some bits still to be hammered out, mainly getting the MyST markdown parser to play nicely with the RestructuredText automatic-Table-Of-Contents magic. But, at the moment, the files in the _build/html/ directory should be correctly linked together and readable while offline.

Comments and suggestions on the CSS and HTML are welcome! Looking at it, the tables and code blocks need some attention. Other itches probably need scratching, too.

[n8willis]

Putting this open for review now!

This branch adds a Sphinx-based local HTML page-set as the output for the documents.

• Long-term, the goal is to move away from "only usable on GitHub.com" docs.
• To build these, you'll need Sphinx; there are more detailed instructions & links in the BUILD.md file.
• When you build them, you end up with a local set of files.

Feedback wanted about output

It is important to know about everything that breaks, however, the most important thing at this stage is how well the generated HTML pages work.

There is a lot of tweaking and formatting involved in the page output, and because the formatting affects the semantics of the docs for people who read them, ambiguities and confusing things really need to get caught. So, in all seriousness, no minor nitpick is too small.

A couple of specific things to call out:

The Bengali document previews some deeper changes than the others

You can start there if you want to see those. Namely:

• It re-titles the <bng2> "shaping stages and steps" links within the documents. Previously (and in the other docs), they just had numbers: "3.3 akhn" or "4.2 pre-base matras". This caused a big problem when trying to add generated numbering for the pages and sections within Sphinx ... which is an important goal for referencing. Internal to each doc, though, the text has always tried to say things like "stage 3, step 3"; the change is that now the HTML sections are called that, too. I think it helps, but let me know if it hurts.
• It adds a <samp> element wrapper to all strings that represent an input or output sequence. In looking at the markup, I decided this was important. We already have several other varieties of semantically-marked-up material in the same document, like programming tokens and literals (i.e., BASE_POS_LAST or U+200D). So things like "Consonant,Halant,Ra" did not fit into that category, but needed to be distinguishable because they're important. There are definitely some grey areas where you could make a case for one markup or the other; it might not be possible to please everyone in those cases, but definitely comment on any missed ones you see.
• It wraps each image in an HTML <figure> element. This lets them have a caption and a number, which I think helps their overall readability, and might be useful to extend to things like tables and big code blocks as well (e.g., regular expressions). The only down side is that the markup to do it in Sphinx looks bad on GitHub's built-in repo view. It could just all be search-and-replaced with inline HTML elements; I'd like to know.

It uses local copies of the Source fonts

This branch started out using the Souce Serif/Sans/Code family from Adobe be Google Fonts, but the static versions served remotely didn't allow for tweaking the CSS well enough or using some of the features. So, instead, the variable-font files are included in the build _static tree. They have their own license (OFL), which is included in the folder.

Numbering everything is not easy

I believe that having per-section numbering of things is critical to new readers keeping track of where they are and to how people reference or talk about things. It is proving kind of tricky to get Sphinx to follow orders in that regard, however.

In particular, the "shaper" section docs themselves are nested for Indic2 and Arabic-like, and I haven't yet gotten the multitoc-numbering extension to behave. It looks like it's breaking on double-nested subtrees being the top item of a TOCtree, but I haven't yet tried to dig in. There is an open issue on that upstream with the extension here: executablebooks/sphinx-external-toc#89 ... which looks like it's not getting active looks. So if you want to dive in to that, separate from all the HTML juggling, that'd potentially be worthwhile.

Regardless, feedback on whether or not the numbering is useful would be helpful (remember to compare Bengali and other docs, though, due to the change mentioned above)