docs: Comply with Diátaxis

[PierreQuinton]

This dev branch makes the transition toward compliance with Diátaxis.

• Changes docs to reference
• Create Explanation
• Create Tutorials
• Create How-to guides

We can partial merge this to main with any release.

When merging main to this, should verify:

• docs/source/docs is empty, if not, it should be moved to docs/source/reference and cross references should be fixed.

[ValerianRey]

Really cool to see that there was some effort to standardize the technical documentation specs.
I still have to read it thoughoughly.

I put the breaking change flag because this will break some existing links (from outside of torchjd to our docs). But I don't think it's a big issue (it's not like there are so many of those links out there).

EDIT: just saw the redirecting script. If I understand correctly the old links will still work. Removing the breaking change flag.

[ValerianRey]

If I understand correctly:

• We have some tutorials but very basic and a bit outdated IMO (https://torchjd.org/stable/examples/basic_usage/, maybe some parts of the readme)
• We have some how-to-guides, which are the rest of our examples. I think those are quite ok, even though we could add more / improve the existing / reorder them.
• We don't really have Explanation apart from the paper and the beginning of the readme. We could probably improve a bit on that.

IMO we should mainly improve on tutorials and simplify the readme (which is currently a mix of everything).

[PierreQuinton]

Exactly right, the goal of this is not to do all of it, just to go in that direction/structure. This definitely will break the ice for newcomers, while keeping experts comfortable. I believe this is a significant improvement. So my goal for now is really to structure it that way, then we shall of course make the content changes.

[PierreQuinton]

@ValerianRey I think we do not check links on the built docs, should we do that (and make the link checker dependent on the doc builder)?

[PierreQuinton]

I think this is more or less the right scope for this PR, we can merge on release. (the link checker fails because of the links in the README).

Note that _redirect.py is fully generated, I don't know how/if it works, we could in priniple also redo it entirely, it seems to be a little bit too complicated in my opinion. It could also be something we add in the doc repo to ensure backward compatibility of links in a more definitive way.

[ValerianRey]

@ValerianRey I think we do not check links on the built docs, should we do that (and make the link checker dependent on the doc builder)?

Why would we need to do that? I think this action has to many false positives to be used everywhere.

[ValerianRey]

I think this is more or less the right scope for this PR, we can merge on release. (the link checker fails because of the links in the README).

Note that _redirect.py is fully generated, I don't know how/if it works, we could in priniple also redo it entirely, it seems to be a little bit too complicated in my opinion. It could also be something we add in the doc repo to ensure backward compatibility of links in a more definitive way.

Shouldn't how-to-guides and tutorials be reversed in terms of content? IMO Basic Usage is a tutorial, and the other examples are more How-to guides.

[ValerianRey]

Note that _redirect.py is fully generated, I don't know how/if it works

Can we test it with local documentation building? Also, please try to review all AI-generated code yourself before asking for reviews (otherwise it duplicates the effort so it kinda kills the point of using AI)

[ValerianRey]

Do we really care that much about changing the url from docs to reference? I think we used docs to match what's done in torch. And from reading Diataxis, I don't think it's a strict requirement to match exactly the names that they use. In my understanding, it's more of a way for us to understand what kind of information we're trying to convey.

It also makes the URLs longer.

So I don't think the 500 lines of AI-generated code for redirects (or breaking change of url if it doesn't work) are worth it.

[ValerianRey]

I think this PR should focus on splitting tutorials and how-to-guides, and later we can make tutorials more compliant with the dataxis structure (see how tutorials in https://www.gatsbyjs.com/docs/ are structured), make more of them, and maybe improve a bit some of our how-to-guides.

Let's go step by step, this is a long journey.

[PierreQuinton]

I don't like this anymore.

[KhusPatel4450]

Hello, I think there is a better way we can do this, we are kind of overcomplicating it, give me some time