Document tagged versions as well as latest `main`

[adigitoleo]

Pdoc needs some extra steps for documenting multiple versions. Luckily, it seems someone has already come up with a way to do it: mitmproxy/pdoc#470 (comment). We can use that to either document the most recent tag + main HEAD or all tags + main HEAD.

[adigitoleo]

Documentation should include the version number next time it builds on top of a tag (after #207). Need to test this with a v0.1.0-rc1 tag soon (not necessary to have a new PyPI release until v0.1.0 proper, but could be nice).

• Ensure that documentation website includes version number (9b58702)
• Modify docs.yml to build for all tags, not just latest
• Add version selector to the website (javascript, see linked comment above) (d753903)

I don't think we need to worry about also building docs for HEAD on main, building them offline is very simple (c.f. Sphinx, Doxygen, ...)

[adigitoleo]

We don't want to store built docs for earlier versions in the repository; at the same time, doing git checkout on an earlier version and trying to build the docs is not likely to just work, because (transient) dependencies may have been updated since then (and I don't want to pin fixed versions of all dependencies for each PyDRex version). For example, trying to build the docs for v0.0.1 again now fails because we had NumPy 2.0 come out in the meantime.

Part of the problem is that building the docs with pdoc fundamentally requires importing the package (dynamic analysis), but I think that is the same for most Python documentation builders. The options here are: (1) forget about building docs for old versions, since we probably won't be maintaining them with backported patches for such a project or (2) store the built docs for older versions in some persistent online storage somewhere and re-download them into subdirectories of html/ when deploying the docs.

[adigitoleo]

For option (2), we could store the built HTML docs for old tags as github release assets and redownload and unpack them during deployment of a new version. That seems like the best way to accommodate keeping docs online for old versions while avoiding slow/wasteful rebuilds of all docs versions on every deployment and pinning of dependency versions for all tags.

This will force me to finally adopt github releases which I was trying to avoid 😅 but maybe that's a good thing.

[Patol75]

That sounds good to me. Time to get these GitHub Releases going. :p