doc: improve and restructure the docs

[frostming]

Pull Request Checklist

• A news fragment is added in news/ describing what is new.
• Test cases added for changed code.

Describe what you have changed in this PR.

Close #1678

[hynek]

• I don't think "references" is the plural of "reference articles". The section is just "Reference" or "Reference Guides" (cf. e.g. https://docs.djangoproject.com/en/4.1/). References are people that vouch for you skills when you're asking for a new jobs.
• as for the structure: have you seen https://diataxis.fr?

[frostming]

• I don't think "references" is the plural of "reference articles". The section is just "Reference" or "Reference Guides" (cf. e.g. https://docs.djangoproject.com/en/4.1/). References are people that vouch for you skills when you're asking for a new jobs.

Thank you, updated.

• as for the structure: have you seen https://diataxis.fr?

Yes I have, that is a beautiful doc site. But I didn't have it in mind when I am restructuring. I just think we need a tutorial-like structure for Usage section.

[pawamoy]

We should make sure to setup redirects for pages that don't exist anymore, to avoid breaking existing links to the docs. This can be done with mkdocs-redirects for example.

[frostming]

We should make sure to setup redirects for pages that don't exist anymore, to avoid breaking existing links to the docs. This can be done with mkdocs-redirects for example.

Thanks for the recommendation, #1688