DOC: Rewrite installation instructions

[timhoffm]

• Put pip and conda as the most common options first
• Don't distinguish Linux / Windows in the pip commands. They are equivalent and users should be able to get this right even without the distinction.
• Replace the venv instructions by a general tip to use environments and link out for details.
• Collect all OS-specific package manager in one section
• Remove the "Windows - Other methods" secion. This is basically pip (or conda). It's beyond the scope of Sphinx to explain how to set up Python.
• Move latest development release to a separate entry.
    Question: Do you still do development releases? I just got the latest stable by that.

[n-peugnet]

You should take a look at this related issue: #12318

[timhoffm]

@n-peugnet thanks for the hint. IMHO this PR is mostly in line with the discussion. The only difference is, that I've put the environment creation in a tip at the top and link out for details instead of walking the users through explicitly.

The motivation is the following. Sphinx users, i.e. people who care to produce compiled documentation are likely not the very beginners. Since environments are quite common nowadays I expect that most sphinx users will have a basic understanding of environments. Walking through the environment creation process is rather a distraction for the experienced user (they know the installation scpoe they want when they see a pip install or conda install command). For the inexperienced user, who is "blindly" following a recipe, it might still not be helpfull to start from scratch. They may have already followed another guide to set up a dev env and creating a separate doc environment is not ideal, e.g. because of potential import issues for autodoc and missing dependencies. Additionally, there are virtualenvs and conda envs and different tools (venv, poetry, pipx / conda, mamba ...) so that one definitive guide is not possible.

Overall, I believe that the environment topic is too diverse and complex to be addressed meaningfully inside the Sphinx installation guide. Thus we should recommend to use environments but not try to explain their usage explicitly.

[chrisjsewell]

thanks for the explanation @timhoffm, will try to have a look soon

[chrisjsewell]

Thanks!

Definitely agree with the re-ordering and addition of conda,
just some suggestions for installing with pinned dependencies

[chrisjsewell]

all good!

[timhoffm]

Side question, which was not answered above: Do you still have development releases or should the section be removed?

[chrisjsewell]

Side question, which was not answered above: Do you still have development releases or should the section be removed?

well not currently, but lets leave in for now as might when approaching v8