Render schemas in separate folder to schema sources

[dstansby]

Currently running pre_build.py places the rendered schemas (markdown and HTML) in the same folder as the schema sources (/schemas). To avoid cluttering up that folder, and make it obvious that the rendered versions shouldn't be committed/edited, it would be nice to have the rendered files outputted to a separate directory (/_build?)

[jo-mueller]

Hi @dstansby I went back and forth on this one a bit. Ultimately, my main rationale for not spawning autogenerated markdown/html in a separate folder was that I wanted clean URLs for the built pages.

I.e., if an autogenerated markdown files is put into /examples/index.md, it will later be available under the URL ngff.openmicroscopy.org/specifications/<version>/examples/index.html. However, if I place it in /_examples/_build/index.md, it will later appear under ngff.openmicroscopy.org/specifications/<version>/examples/_build/index.html.

At the end of the day, I favored the clean URLs over the cleaner folder structure, especially since the built files do not appear in the repo itself.

Maybe Jupyter book/Sphinx offer some customization tools for this (beyond redirects).