Versioned Sage documentation - Githubissues

sagemath / documentation

Only hosting https://doc.sagemath.org/ files. Updates to the documentation must be made with PRs to https://github.com/sagemath/sage, not here.

https://doc.sagemath.org

11 stars 9 forks source link

Versioned Sage documentation #24

Open mkoeppe opened 3 years ago

mkoeppe commented 3 years ago

(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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

Sounds great.

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

mkoeppe commented 3 years ago

deployment script running on GH Actions

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

culler commented 3 years ago

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 commented 3 years ago

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 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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

mkoeppe commented 2 years ago

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

haraldschilly commented 2 years ago

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 commented 2 years ago

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

tobiasdiez commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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

MahakkSingh commented 5 days ago

kindly assign me this issue

haraldschilly commented 5 days ago

kindly assign me this issue

what's your plan how to deal with this?

Are you aware of this script, which outlines how to access older versions? https://github.com/sagemath/documentation/blob/gh-pages/old_versions.py

MahakkSingh commented 5 days ago

no i am a newbie you can guide me

On Fri, 29 Nov 2024 at 19:55, Harald Schilly @.***> wrote:

kindly assign me this issue

what's your plan how to deal with this?

Are you aware of this script, which outlines how to access older versions? https://github.com/sagemath/documentation/blob/gh-pages/old_versions.py

— Reply to this email directly, view it on GitHub https://github.com/sagemath/documentation/issues/24#issuecomment-2507921017, or unsubscribe https://github.com/notifications/unsubscribe-auth/BJCIHMNOZ4QMSTL7IMLRVV32DB2NVAVCNFSM6AAAAABSW5FE7SVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDKMBXHEZDCMBRG4 . You are receiving this because you commented.Message ID: @.***>