Improvements to docs infrastructure

[penelopeysm]

• Closes Manifest.toml files are outdated #495
• Closes Quarto freeze files shouldn't be loaded from cache if environment is different #496
• Also fixes some typos in https://turinglang.org/docs/versions.html ('Documention' -> 'Documentation')
• Adds some extra files that should be gitignored (Quarto requires a python venv to run, so I added the typical venv and .venv paths)

Please see issues for more details!

[github-actions]

Preview the changes: https://turinglang.org/docs/pr-previews/497
Please avoid using the search feature and navigation bar in PR previews!

[penelopeysm]

Unfortunately, GitHub is still running the version of the workflows on the main branch, so the current PR preview doesn't show the correctly built docs (for example, it still has the UndefVarError I mentioned in #495).

To get around this, I'm going to temporarily add a new workflow file that runs on this branch, then remove it after it's done running.

Edit: The workflow ran at: https://github.com/TuringLang/docs/actions/runs/10131613167/job/28014548724?pr=497 and the preview docs now reflect the docs that would be built if this PR were merged.

[penelopeysm]

(@shravanngoswamii Requesting your expertise on github actions here :))

[shravanngoswamii]

I had kind of assumed that after we upgrade master to 0.34, we would then also create a backport-v0.33

Actually, we created the backport of v0.32 because it was released when I was developing versions workflows for this repo!
See here, we are publishing rendered docs of old versions in gh-pages itself:
https://github.com/TuringLang/docs/blob/b65e747ccc8ea125b83a1db6f3de80c0bb839947/.github/workflows/publish.yml#L45C1-L52C55

https://github.com/TuringLang/docs/blob/b65e747ccc8ea125b83a1db6f3de80c0bb839947/.github/workflows/publish.yml#L93C1-L99C23

gh-pages: https://github.com/TuringLang/docs/tree/gh-pages/versions

[shravanngoswamii]

In current workflow, we have to create a branch from some old commit and then update the old docs by changing version number in _quarto.yml

[penelopeysm]

In current workflow, we have to create a branch from some old commit and then update the old docs by changing version number in _quarto.yml

Yeah. I think we are agreeing, right? ;) The docs for v0.33 would live in a v0.33 branch (we can call it backport-v0.33 for consistency, or we can take a different name, not a big deal). The Project.toml and _quarto.yml on that branch would be kept at 0.33. Then we make edits on that branch if we want to change old docs. As long as we keep the structure of those branches in agreement with the publish workflow, I don't see any problems arising.

[shravanngoswamii]

Is it fine to create a lot of branches, because they will keep increasing!

[penelopeysm]

Personally I wouldn't have a problem with it! As long as we are publishing multiple versions of the docs online, the source for those versions will have to live somewhere, and this repo is the most logical place to house them.

Most software projects I know do this too, for example the Julia core repo has release/vX.Y branches with all the docs which (I presume) is how they keep docs for old versions online :)

If we find one day that there are too many branches, then we could just stop providing online documentation for old versions. For example, we could say that we provide docs only for the 5 latest versions. We could discuss that in the future, but I can't say I feel particularly bad about using GitHub's disk space haha.

[shravanngoswamii]

We could discuss that in the future, but I can't say I feel particularly bad about using GitHub's disk space haha.

Well, I agree to all your points! I am approving changes from my side! Maybe @yebai would like to review it before merging!

[shravanngoswamii]

@penelopeysm Thank you for all the effort!!

[yebai]

@mhauru can you take a look too, and approve before merging?

[mhauru]

Had a few questions and small comments, seems great. That auto-version-updater GHA is faaancy! I wonder if the Julia code for it could live in a .jl file somewhere. Having that much Julia code as a string in yaml feels funny, and exempts it from things like linting.

[mhauru]

Looks great, thanks Penny!

[penelopeysm]

Thanks everyone!