Proposal: move to RTD

[joshmoore]

This branch contains the necessary bootstrapping to deploy the specifications as well as other sphinx pages on https://readthedocs.org:

• conf.py runs bikeshed which is copied via html_extra_path
• index.rst redirects to latest/index.html as before
• about/index.md is available as a new top-level landing page

This was largely done in order to provide the ngff.openmicroscopy.org/tools and ngff.openmicroscopy.org/data URLs as decided in theOME-Zarr preprint:

• tools/index.rst is largely done and driven by lists.csv (but could look nicer)
• data/index.md is a simple but linked table at the moment
• publications/index.md has been added but is still unpopulated

The current branch can be reviewed at https://ngff.readthedocs.io/en/rtd/about/index.html . Once this PR is merged, https://ngff.readthedocs.io/en/latest/about/index.html would become a new default landing location without further configuration and the URLs needed can redirect to, e.g., https://ngff.readthedocs.io/en/latest/tools/

We should likely consider renaming the sphinx-specific latest to not conflict with the spec-specific latest, otherwise we get a default URL of https://ngff.readthedocs.io/en/latest/latest/index.html . If there's a general consensus, we could also redirect https://ngff.openmicroscopy.org away from GitHub pages and to https://ngff.readthedocs.io. Additionally, we can drop the redirect to latest/index.html in favor of a top-level landing page like about/index.md.

TODOS:

• Tools: Move tools table to long-form markdown
• Data: Fix DANDI URL parsing
• Data: Combine names with URL, add description column
• Publish schemas (see example)
• Redirect DNS
• Create issue for collecting logos (cf. https://zarr.dev/adopters/)

[github-actions]

Automated Review URLs

• render latest/index.bs
• diff latest modified

[will-moore]

Looks nice! 👍

[bogovicj]

Is it right that this could help divide "strictly spec" from "spec-adjacent" (e.g. examples) to different pages? Hopefully resulting in a less cluttered spec?

[joshmoore]

From my POV, that's certainly an option, sure. An additional next step that could go in the description of this PR but I didn't really want to get in is that we could drop bikeshed in favor of some flavor of plain markdown. That might make it easier to refactor more readily in this repo.

[joshmoore]

Ok, I think that includes all the "must-fix" items. Biggest question remaining in my mind is whether or not to set the Single version flag:

A single version site has no translations and only your "latest" version, served at the root of the domain. Use this with caution, only turn it on if you will never have multiple versions of your docs.

If we do that, then once DNS is re-directed, all previous URLs should continue working.

[joshmoore]

Discussing during the "Zarr Resources" call with @will-moore and @pwalczysko, we're going to merge this and drop the en/latest from the URL in order to prepare for DNS migration.

[joshmoore]

@ome/ngff: https://ngff.openmicroscopy.org/data/ is now live with a DNS entry to readthedocs.io