Versioned Sage documentation

[mkoeppe]

(from https://groups.google.com/g/sage-devel/c/oWkFwhinoMc/m/EOL1TZphBgAJ)

keep online documentation of each release, that is having:

• https://doc.sagemath.org/VERSION/ for each release
• https://doc.sagemath.org/current/ (or "latest") pointing to the doc of the last release
• https://doc.sagemath.org/develop/ for the current beta

Currently some links on the web (e.g. on ask.sagemath.org) are outdated as the discussion does not correspond to the current state of the doc.

[haraldschilly]

I've moved this to the documentation repository, because it's not about the sage website. Besides that, I don't like just throwing in "/current/" in the URL, because that would break all existing links from anywhere else worldwide.

[mkoeppe]

I agree that "current" is redundant and should just be the existing https://doc.sagemath.org/ so that external links do not need updating.

[haraldschilly]

Ok. Older versions are in the commit history, it's not lost. It's just that I don't have time to move things around properly. I also don't know if we're already hitting an overall limit regarding size. So far, I haven't seen any warnings. So, maybe for the next sage release, I'll try to setup a sub-directory for the then previous version and we can see how this works.

[mkoeppe]

Sounds great.

Perhaps a deployment script running on GH Actions could help reduce your workload?

[mkoeppe]

deployment script running on GH Actions

I've opened https://trac.sagemath.org/ticket/31415 for this

[culler]

I also don't know if we're already hitting an overall limit regarding size. So far, I haven't seen any warnings.

According to the Github documentation, sites on Github Pages sites are limited to 1GB with a bandwidth limit of 100GB per month. The documentation files created by running make in the sage source directory use almost 1GB. And a Github Pages user is limited to one site. So it looks to me like there is no possibility of hosting documentation for multiple versions of SageMath on Github Pages.

One alternative would be to store the files in Amazon S3 and use Amazon Cloudfront as the CDN. That is not free, although it is also not super expensive. S3 storage seems to cost about $0.023 per GB per month, and the Cloudfront service appears to cost about $0.10 per GB of data transferred and about $.01 per 10,000 html requests. So the bill would probably be under $10 per month.

[haraldschilly]

I implemented serving older pages with deployment via a CI/CD job in gitlab. This works, in theory, but in practice the job fails with "too large" errors. It's simply too much to copy over.

So, there is an opportunity fix this issue, but not with the deployment setup we have right now (neither github nor gitlab pages).

[mkoeppe]

The deployment of documentation to netlify for ticket branches (https://trac.sagemath.org/ticket/31415) by @tobiasdiez works nicely. What's missing for making this our standard deployment?

[tobiasdiez]

I think there are a few things that are added in this repo here which are missing in the documentation in the sagemath repo and thus for the version deployed to netlify (for example, the index page https://doc.sagemath.org/ if I remember correctly).

[mkoeppe]

For starters, would it be possible to set up a Permanent Redirect from https://doc.sagemath.org/VERSION/ to the corresponding netlify deployment?

[mkoeppe]

(This would make it easy to add a versions menu such as https://github.com/goerz/docs_versions_menu)

[haraldschilly]

For starters, would it be possible to set up a Permanent Redirect from https://doc.sagemath.org/VERSION/ to the corresponding netlify deployment?

• there are 3 rewrute rules left. there could be one with a pattern, though, where https://doc.sagemath.org/$1 → [something]$1 is rewritten.
• I would only make a temporary redirect, though, until we are sure we do this.
• as mentioned above, the older versions going back to 6.6 are all available and I wrote a script to surface all those versions. The only problem left is to find a way to host this on a webserver with enough storage.

[mkoeppe]

@tobiasdiez Would it be possible to set up an additional NETLIFY_ALIAS when the commit is tagged?

[tobiasdiez]

I'm not sure if --prod and --alias can be combined, but what should work is to duplicate https://github.com/sagemath/sage/blob/ad69a5b07b86a62dd20693056208f234ba4b06b9/.github/workflows/doc-build.yml#L42-L58 and set NETLIFY_ALIAS to the tag name. However, I would suggest to use the release trigger instead of trying to see if the latest commit has been tagged.

[mkoeppe]

We don't do GitHub Releases for beta versions. I think you can just dispatch on GITHUB_REF starting with refs/tags/ https://docs.github.com/en/actions/learn-github-actions/environment-variables#default-environment-variables

[tobiasdiez]

Does one really need to (easily) go back to versions of the docs for different beta/rc versions? I think having older versions for each release + current develop branch should be sufficient. Otherwise the user interface for choosing the different versions gets quite complex.

[mkoeppe]

I think having older versions for each release + current develop branch should be sufficient.

Sure, in the user interface even displaying all older versions would be too much.

[mkoeppe]

I've opened https://trac.sagemath.org/ticket/33862: doc-build.yml: Set NETLIFY_ALIAS to the tag name