Reorganising developer section

[penelopeysm]

In general, I think we could be making much better use of a directory structure to keep different tutorials etc. Also the numbering system of docs-01, docs-02, ... is genuinely really unwieldy.

At first, I thought that we were doomed to keeping the old structure because of backwards compatibility for URLs. (It's kind of annoying as a user to click on a bookmark and get a 404.) Then I learnt that Quarto lets you give each page aliases, like this: https://quarto.org/docs/websites/website-navigation.html#redirects which means that we can move our pages around as much as we like, as long as we keep the old links as an alias.

This PR therefore moves all the documentation in the 'developer' section to a cleaner directory structure, preserving all the old links.

Note that in the PR preview all the old links still redirect to the correct page:

• https://turinglang.org/docs/pr-previews/572/tutorials/docs-01-contributing-guide/
• https://turinglang.org/docs/pr-previews/572/tutorials/dev-model-manual/
• https://turinglang.org/docs/pr-previews/572/tutorials/docs-05-for-developers-compiler/
• https://turinglang.org/docs/pr-previews/572/tutorials/14-minituring/
• https://turinglang.org/docs/pr-previews/572/tutorials/16-contexts/
• https://turinglang.org/docs/pr-previews/572/tutorials/docs-06-for-developers-interface/
• https://turinglang.org/docs/pr-previews/572/tutorials/docs-04-for-developers-abstractmcmc-turing/
• https://turinglang.org/docs/pr-previews/572/tutorials/docs-07-for-developers-variational-inference/
• https://turinglang.org/docs/pr-previews/572/tutorials/docs-17-implementing-samplers/

Apart from this, I also added a note to the "compiler design" title to say that it's outdated (some of the DynamicPPL functions referenced there do not exist anymore).

If we are OK with this approach, then I will work on cleaning up / reorganising the 'users' section after this is merged.

[github-actions]

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

[penelopeysm]

Apologies for the large diffs, none of the content in the actual qmd files is changed (apart from adding the necessary aliases). I think git has just changed CRLF to LF or vice versa.

_quarto.yml provides pretty much a complete overview of the things that changed, I think the rest can pretty much be ignored.

[penelopeysm]

Maybe this one for you, @mhauru - let me know if you have better suggestions for directory structure

[mhauru]

I'm very happy with the changes themselves, this is much clearer.

I worry a bit about the line break character changes. Why did this only happen for some files? Do we still have a mixture of line break characters in the repo? Why did we get a mixture in the first place?

My worry is that there will be more PRs in the future where line breaks change, which makes diffs unreadable. Worse yet, an oscillation where we keep changing the line break chars back and forth. There's some git setting for forcing it to use a particular line break character. If I remember correctly it allows you to checkout a commit, and git will automatically convert line breaks to your system's native one, and then convert back to the repo default when you make a commit. Maybe we need to set that in a local .gitconfig?

[penelopeysm]

Why did this only happen for some files?

I think that it's because of different operating systems. The qmd's were probably written on Windows and checked in with CRLF. The two files that didn't have a huge diff were model-manual.qmd, which I think I created, and implementing-samplers.qmd, which was Tor, so it must have been checked in with LF, since we're both on Unixy systems.

Maybe we need to set that in a local .gitconfig?

In the past it used to be that Windows contributors would need to set core.autocrlf = true, and Unix/Linux contributors to core.autocrlf = input. That would make sure that the repo itself only had LF, but when checked out, each contributor's working directory would contain their native line ending. That's what I learnt when I first started using Git, anyway 😄

Apparently, nowadays you can use a .gitattributes file to enforce this for all contributors. https://docs.github.com/en/get-started/getting-started-with-git/configuring-git-to-handle-line-endings#per-repository-settings That might be a good idea, since we may (or hopefully will?!) have many ✨ contributors ✨ using different operating systems.

For this PR, I've reverted the checked-in line endings to the originals, so that the diffs are easy to read. I can follow this up with a PR to normalise everything to LF and to add the .gitattributes file so that it stays that way in the future.

[penelopeysm]

That does raise a question of whether every repo should have a .gitattributes, not just this one...

[mhauru]

Very happy with this PR.

I wasn't familiar with .gitattributes, it seems really neat.

[penelopeysm]

I checked the holy trinity of Python data science packages and they all seem to make at least some use of it

https://github.com/numpy/numpy/blob/main/.gitattributes

https://github.com/scipy/scipy/blob/main/.gitattributes

https://github.com/matplotlib/matplotlib/blob/main/.gitattributes