Improvements to docs infrastructure

[penelopeysm]

• Closes #495
• Closes #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[bot]]

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]

@penelopeysm after this is merged, what will be the ideal process of updating the documentation of old versions!

[penelopeysm]

@shravanngoswamii That's a good point. Am I right in saying that only 0.32 is generated via this repo?

If that's the case, I suspect the only change we need to make on the backport-v0.32 branch is to coalesce the envs into a single Project.toml with the appropriate compat entry for Turing, and it should work fine with the present workflow.... I think.

[shravanngoswamii]

Not only v0.32, let's say we are on v0.36 and some changes are required in v0.34 (which is not backport)!

[penelopeysm]

Hm. I had kind of assumed that after we upgrade master to 0.34, we would then also create a backport-v0.33 branch that would just be the contents of master prior to upgrade. Those could then be edited however we wish and should be published just fine by the current workflow.

[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?

[penelopeysm]

Thanks everyone!