As part of migrating m3api away from GitHub in general (see the parent task), doc.wikimedia.org seems like a good new home for its documentation. I’ve been told (below this thread) that “volunteer” projects can be accepted there :)
The general documentation setup, which I’d like to keep, is that each release builds its own documentation, and then that documentation is mostly left untouched later. If I want to completely switch the documentation generator from JSDoc to something else in the future, I can do that and the past documentation won’t be affected – which means I won’t have to check if the doc comments of the past versions all render correctly.
More specifically, documentation is currently hosted via GitHub Pages. Each release checks out the gh-pages branch; adds a “This is an old version. The latest stable version is [link]vx.y.z” warning banner to the previous latest version, and also updates those banners in all the older versions; then builds the new docs. (GitHub Actions workflow, example commit.) There is also a small index.html file at the docroot to redirect to the latest version (this is also updated with each release). This design has several characteristics I consider desirable: when people look at the documentation and copy the link, that link will stay stable (because it always has the version number in the URL); there is a “latest” URL but only for the docroot (“latest” links for any particular class or function would break when that class or function is removed or renamed); when people load the documentation for an older release, they see a warning, but they’re not automatically redirected away.
The usual workflow for doc.w.o seems to be to just rsync the freshly built current docs over (either into a subdirectory named after the version, or directly into the project root if you only want latest documentation); the docs aren’t tracked in a separate Git repository or branch. However, to make something like the above process work (including updating the “latest version” banners in all the old docs), I think the easiest solution will be to have the docs in a Git branch after all, and do something pretty similar to the GitHub pages setup – and then to just rsync all the docs over at the end (and let rsync work out that e.g. /v1.0.0/styles/ didn’t change).
