Publish all spec versions

[gouttegd]

Resolves [#530]

• docs/ have been added/updated if necessary
• make test has been run locally
• tests have been added/updated (if applicable)
• CHANGELOG.md has been updated.

This PR implements what has been proposed in #530: A website that shows, not just the current development version of the specification, but all previously released versions (currently only 1.0, since that’s the only release we have so far) as well.

This is done by:

(A) Moving all the normative pages of the website into src/docs/spec (instead of leaving them in src/docs). Strictly speaking this is not entirely necessary, but this allows to make a clear distinction between what part of the website is the actual spec, and what part is non-normative documentation. This is turn makes it easier to show different versions of the normative part on the same website.

(B) For every past release X.Y (so, for now, only 1.0), we check out a Git submodule under releases/vX.Y, pointing to a tag or branch corresponding to the X.Y release. Then we add a new Make target gendoc-vX.Y that (1) copies all files from releases/vX.Y/src/docs/spec/ (that is, all the normative files from the X.Y version) into $(DOCDIR)/spec/v1.0 and (2) generates the LinkML-derived documentation from releases/vX.Y/src/sssom_schema/schema/sssom_schema.yaml (the version of the schema as it was in the X.Y release) and puts them in $(DOCDIR)/src/v1.0.

The gendoc Make target will produce a website containing only the development version of the spec. To build a website containing all versions, use the new gendoc-full target.

The end result is that, at any time:

• https://mapping-commons.github.io/sssom/spec/ will point to the current development version of the spec;
• https://mapping-commons.github.io/sssom/spec/vX.Y will point to version X.Y.

Because cool URIs don’t change, and since until now all the pages from the spec were directly under https://mapping-commons.github.io/sssom/, the PR also adds all the necessary redirects to ensure that any URI pointing to an old location remains valid.

[gouttegd]

Reviewers: if you want to test what the “versioned“ website would look like with this PR:

git fetch origin
git checkout origin/publish-all-spec-versions
git submodule init
git submodule update
make gendoc-full serve

Then navigate to https://localhost:8000/sssom.

[matentzn]

For me locally images didnt render:

My main problem is that its now very easy to go to the "wrong docs" (it does not matter what we mean by wrong here).

1. the search indexes all sites equally without discrimination - and therefore becomes useless.
2. There is no visual distinction on the pages of one version to which version it pertains (like on, say, w3org specs etc)

Why not use https://squidfunk.github.io/mkdocs-material/setup/setting-up-versioning/?

[matentzn]

Maybe pin this as well just to be in the habit?

[gouttegd]

I’d need a better reason that just “to be in the habit”.

I am against pinning in general unless it is justified.

[matentzn]

My opinion on this is super weak and could be overruled by a mild breeze: pinning development dependencies (like docs) seems to help keeping things running smoothly; i am totally against any kind of client facing runtime dependency pinning of course. Anywyas, up to you.

[gouttegd]

the search indexes all sites equally without discrimination - and therefore becomes useless.

That’s a valid point, but I don’t see how versioning the entire website (as would be the case with https://squidfunk.github.io/mkdocs-material/setup/setting-up-versioning/, compared to versioning only the normative section) would change anything to that?

Why not use https://squidfunk.github.io/mkdocs-material/setup/setting-up-versioning/?

This would create completely different websites for everything (not only the normative section, but all the non-normative documentation and other pages – e.g. credits, funding, etc. – as well). That seems completely overkill to me.

[matentzn]

This would create completely different websites for everything (not only the normative section, but all the non-normative documentation and other pages – e.g. credits, funding, etc. – as well). That seems completely overkill to me.

I would not say its overkill. 80% of the users will use the dev site (which is default), and they can search it normally. the 20% will switch to the 1.0 version only if they care to look up stuff on the spec - they wont care about the outdated stuff.

An the "overkill" here has multiple dimensions, why not use something out of the box rather than build it custom? Not convinced.

[gouttegd]

Why not use https://squidfunk.github.io/mkdocs-material/setup/setting-up-versioning/?

[…] That seems completely overkill to me.

Of course I will not admit that this has nothing to with the fact that I didn’t know about mkdocs-material versioning feature. :p

[gouttegd]

why not use something out of the box rather than build it custom? Not convinced.

Fine. :) Might as well close this PR then, because any solution based on https://squidfunk.github.io/mkdocs-material/setup/setting-up-versioning/ would be so different that there is no point in using that PR as a basis.