Proper documentation versioning

[M-Lampert]

Currently, we have paused the stable release of our documentation since we don't have a stable release yet. Before we publish our first stable release, we should change that. This includes the following changes:

Blocks versioning

• docs-dev.yml:35 — drop mike set-default --push --allow-empty dev. This runs on every push to main and undoes docs-stable.yml:28, so the first merge after publishing release docs sends the root of www.pathpy.net back to the dev docs. The default should be owned by the stable workflow alone.
• mkdocs.yml:82 — default: dev → stable. mkdocs-material flags a page outdated unless the current version's aliases match extra.version.default, so with dev every visitor to the release docs gets the "You're not viewing the latest version" banner from main.html:19-24. Use [stable, dev] if we want no banner on either.

Fixes

• docs-stable.yml:28 — add --allow-empty. set_default only rewrites index.html; re-dispatching stable docs produces an empty commit and mike errors out. docs-dev.yml already passes it for this reason.
• docs-stable.yml:3-4 — nothing triggers stable docs from a release, and with no ref input the job documents whatever ref it's dispatched from. Add a tag/release: trigger, or at least a ref input so it can't be run against the wrong commit.
• mkdocs.yml:12 — edit_uri: edit/main/docs/ is baked into every build and feeds the Colab link at main.html:11, so the frozen 1.0.0rc1 docs will link to notebooks on main that have since moved on. Needs to be ref-dependent at build time.
• docs-dev.yml:33 — mike delete --push $(mike list | grep dev | ...) resolves correctly once stable exists, but fails rather than no-ops when the substitution is empty (e.g. a rebuilt gh-pages). Worth guarding.

Remove Documentation comments

• getting_started.md:33-34 — the !!! warning "TODO" about no stable release yet becomes wrong as soon as this lands.

New Feature:
In addition to the warning that an outdated version is viewed, we could also add a warning if the dev version is viewed, since that might contain content that is not released yet. It could be added in docs/overrides/main.html as follows:

{% block announce %}
  {%- if config.extra.docs_version.endswith("-dev") -%}
    You're reading the development docs — features documented here may not be in a
    released version yet.
    <a href="{{ '../' ~ base_url }}/stable/"><strong>Go to the latest release.</strong></a>
  {%- endif -%}
{% endblock %}

[vineetbansal]

@M-Lampert - I've opened up PR #339 for this. A couple of decisions I made (as I got familiar with mike) are slightly different from what is suggested above, but I've gone through the generated docs locally and they have the same behavior as the one desired:

1. Dismissable message about unstable api if viewing /<version>-dev/ docs.
2. Dismissable warning about not being on the "latest" version, if on anything but the stable docs.
3. dev docs will be the default if no stable docs have yet been released (making the above warning in 2. not really dismissable after all, but that's a temporary issue).
4. Stable docs can be manually released anytime we're ready, plus when we make a release.
5. Colab links link to the correct sha1 hash of the notebook, so it works correctly whether you're viewing the stable docs or the development docs, pointing to the commits in those branches respectively.

[M-Lampert]

Closed with #339 currently merged into dev.