spec
spec copied to clipboard
WebAssembly
[bikeshed] WIP new w3c html
This uses a multihtml Sphinx builder, together with custom HTML layout (layout.html and page.html), to build a document that matches w3c requirements.
Currently the toctree directive does not work right, so it is duplicated in the side bar (https://github.com/sphinx-doc/sphinx/pull/9830). The W3C styles also don't apply fully to the side bar (because the Sphinx generated TOC doesn't have the right class name, but this might be fixed by some JS).
layout.html is used for all pages, index + individual pages, so the front matter is guarded by a check that the current page is index. layout.html is rather large, most of it is the front matter copied from https://github.com/WebAssembly/spec/issues/1386#issuecomment-957347678. page.html is used by all the individual rst pages.
Right now all the configuration lives in a new folder, w3chtml, but it can presumably replace the w3chtml folder.
Many thanks for the W3C doc work.
Just as an FYI, W3C specs don't have to be monolithic; it's up to us to publish as a single doc (maybe nice for folks who want to print?) or a multiple pages (more responsive). It might be possible to publish both, but I imagine that simply publishing a multi-page doc with a link to a printable version would be simpler.
Also, we don't have to work all this out before publishing now; we can add features later.
Many thanks for the W3C doc work.
Just as an FYI, W3C specs don't have to be monolithic; it's up to us to publish as a single doc (maybe nice for folks who want to print?) or a multiple pages (more responsive). It might be possible to publish both, but I imagine that simply publishing a multi-page doc with a link to a printable version would be simpler.
Also, we don't have to work all this out before publishing now; we can add features later.
the PR title is a misnomer, it should just be "new html". I think I called it new single html because the build step followed the singlehtml. Let me fix that.
