Improve documentation SEO, refactoring

[astrojuanlu]

Description

This pull request aims to improve the SEO and the structure of the Orchest documentation.

• For the SEO improvements I drew inspiration from a couple of similar pull requests made in Dask (Better SEO for 10 Minutes to Dask dask/dask#9182, Better SEO for Delayed and Best Practices dask/dask#9194) apart from other sources. In particular, I added .. meta descriptions to all pages, :alt: text to all figures, and be more careful with headers and wording in general.
• For the structure, I drew inspiration from the Diátaxis documentation framework, which is widely used in the community. I noticed two things:
  • The "How to..." page contained lots of almost empty sections, which was annoying when doing searches. e.g. I would search for "git", click the first result, and realize that it was just a link to somewhere else ("your princess is in another castle"). I removed those sections and left only the ones that still made sense, and renamed that document FAQ.
  • There was some reference information (according to Diátaxis: understanding-oriented theoretical knowledge), so I created a separate Reference section that now contains the SDK, the CLI, and the keyboard shortcuts. One could say that the Glossary also fits here.

As a side effect, I continued converting some documents to MyST. To review, select the commit range ignoring the first two ones, which (1) upgrade docutils and (2) do all the conversions at once without touching the content. I did not convert all because this PR already moves some stuff around, so I preferred to not touch those documents that got heavily refactored.

Checklist

• I have manually tested my changes and I am happy with the result.
• The documentation reflects the changes.
• The PR branch is set up to merge into dev instead of master.
• I haven't introduced breaking changes that would disrupt existing jobs, i.e. backwards compatibility is maintained.
• In case I changed the dependencies in any requirements.in I have run pip-compile to update the corresponding requirements.txt.
• In case I changed one of the services' models.py I have performed the appropriate database migrations (refer to the DB migration docs).
• In case I changed code in the orchest-sdk I followed its release checklist.
• In case I changed code in the orchest-cli I followed its release checklist.

[astrojuanlu]

🤖 Rendered version: https://orchest--1148.org.readthedocs.build/en/1148/

[ncspost]

LGTM!

[ncspost]

LGTM!

[yannickperrenet]

The "How to..." page contained lots of almost empty sections, (...), and renamed that document FAQ.

From the last Docker based Orchest version we link to: https://docs.orchest.io/en/stable/getting_started/how_to.html#migrate-to-kubernetes. This link would no longer we working with the removal of the page.

Is there a possibility of setting up a redirect?

[astrojuanlu]

Is there a possibility of setting up a redirect?

Luckily yes! https://docs.readthedocs.io/en/stable/user-defined-redirects.html

[astrojuanlu]

Merging, we can continue fixing smaller stuff in later pull requests 👍🏽 Thanks both!

[astrojuanlu]

Hmm pre-commit just failed with an unexpected minor thing 🤔 On it

[astrojuanlu]

gh-1154

[astrojuanlu]

From the last Docker based Orchest version we link to: https://docs.orchest.io/en/stable/getting_started/how_to.html#migrate-to-kubernetes. This link would no longer we working with the removal of the page.

Redirect added 👍🏽