SpatialData specifications: website

This branch (site) holds the website of the SpatialData specifications and the pages of the project itself: the landing page and the contributing guide. The specification has two branches: data-model (the abstract data model, tagged data-model-<version>) and storage-format (one storage format version per commit, tagged storage-format-<version>); each branch holds the current version, its tags the text as first released. This branch builds the storage format versions listed in versions.toml, each with the text of the data model version it encodes, into one site, each under its own directory, data-model/<version>/storage-format/<version>/; the navigation of every page lists all versions. The RFCs are on their own branch, rfcs, without versions: they are built once, into the site root, and every other build links to them there.

Path	Purpose
versions.toml	the published versions: tag, data model and storage format version; the branch of the RFCs
build.py	builds each version from its tag, the data model builds and the root; then shares the assets of the root with all builds, writes the icons into the pages as SVG (no icon script) and writes sitemap.xml, robots.txt and versions.json
site/	Sphinx configuration, CSS, templates and the page present in every build: index.md
site/_ext/static_nav.py	the version navigation, written into every page when it is built: the site works without JavaScript (one script adds tab permalinks)
site/_ext/footnote_previews.py	each footnote shown at its reference on hover or focus (CSS only); printing shows the list of footnotes
site/_ext/data_model_blocks.py	marks the data model text that the storage format page includes (between the % begin/% end markers of data-model.md) with a side rule and a "Data model" label
pages/	pages only at the root: the contributing guide and the pages showing the latest state for every version (implementations); every other build links to them there, its navigation lists them (static_nav.py). The RFCs of the branch rfcs join them there, and build.py writes the table on rfcs.md from their headers
.github/workflows/site.yaml	checks, builds and, on a push to this branch, deploys the site to GitHub Pages
.github/workflows/preview.yaml	builds the site and deploys it to Cloudflare Pages, out of search engines: every push to this branch, data-model, storage-format or rfcs at https://spatialdata-spec.pages.dev/, every pull request against one of them at https://pr-<number>.spatialdata-spec.pages.dev/

Building locally

Needs uv and a full clone (all branches and tags):

uv run build.py --site-url http://localhost:8000/   # every version in versions.toml
uv run build.py --ref some-branch                   # one branch or tag, as a preview
uv run build.py --source ../spatialdata-spec        # a working copy, as a preview
uv run build.py --rfcs-source ../rfcs               # every version, with a working copy of the RFCs
python -m http.server -d _site                      # then open http://localhost:8000/

An entry of versions.toml may also give source = "<directory>", to build it from a directory instead of its tag (for example the output of tools/write_history.py --out on history-draft).

Releasing a version

1. Tag the release commit of main as storage-format-<version>.
2. Add the tag to versions.toml on this branch, above the previous release, and move preferred to it. Never change the directory of a published version: it is part of every permalink.

License

The website code is BSD-3-Clause (LICENSE). The text of the pages in site/ and pages/ (the landing page, the contributing guide and the implementations) is CC-BY-4.0 (LICENSE.md).