install documentation cleanup

[drammock]

Our recommended installation methods have changed a lot over the past couple years, and not all parts of our install documentation have kept up. Here's an abbreviated outline of the current flow (in the order they appear):

- Choose bundled installer or manual install
- bundled installer download page
- manual install page (with side-link to orphaned "installing python" page)
- advanced setup
    - use with jupyter
    - headless server
    - dev version
    - other python distros
    - GPUs / CUDA
    - offscreen MESA rendering
    - troubleshooting 3D plots
- testing your installation
- updating MNE-Python
    - via pip
    - all packages via conda
    - using the dev version (static upgrade via pip)
- Installing Freesurfer
- Overview of related tools

Here are a few problems I see:

• because it's now orphaned, the "installing python" page doesn't get a TOC in the left sidebar nor next/prev links at the bottom
• the most popular/important info is mixed in with niche info (e.g., use with notebooks vs use with other Python distros; using dev version vs using on headless server; etc)
• some of the later content is not clear if it still applies if you use the installers (e.g., nb_conda_kernels in the Jupyter section; freesurfer; related software like MNE-BIDS)
• The "What should I install?" content is now at the very end of the install documentation

Let's use this issue to discuss improvements to the organization / flow of the install documentation pages.

@hoechenberger

[hoechenberger]

Thanks for bringing this up, @drammock, I realized that I didn't like this organization back when I worked on the docs to incorporate info about the installers, but I didn't really know how (or didn't dare?) to re-organize things. Super happy to help getting this cleaned up and reorganized.

My very first intuition would be to consider the installers "the new normal", and not even bother about explaining how to get Python installed – if you need advice on how to do that, maybe you should use our standalone installers instead to begin with. So I suppose manual Python install instructions would be the first thing I'd remove without replacement.

(Just to avoid confusion, I'm talking about how to install a Python distro, not about how to manually install MNE into an existing Python install)

I haven't recently looked at the other parts of the install docs, but will try to do so in the coming days. Feel free to ping me if you don't hear back from me – I have quite a bit of stuff on my plate and need to constantly shuffle tasks, so sometimes I simply forget or de-prioritize things. A friendly poke brings it back up near the top of my to-do list, though ;)

[larsoner]

Optimistically marking for 1.4 so we don't forget to think about taking care of parts of this in that cycle

[britta-wstnr]

From my view - if I just may weigh in here - something like this could make sense:

- What's the right installer for me? - mentioning also complete setups with 3D viz, Freesurfer etc, and links to that documentation
- How to install
- Test your installation
- Update your installation
- What now? -- Where to go to get started with Python, Notebooks, MNE ...
- Advanced setup
    - headless server
    - etc (see list above in Dan's comment)
- Overview of related tools, info about installing them, e.g. Freesurfer

[drammock]

Some notes from dev meeting conversation with @britta-wstnr:

• "advanced setup" page needs to be split/curated
• need a quickstart page
• advice about mamba is a rabbit hole
• python IDEs should not be on the "pip/conda install" page
• update IDEs to include DataSpell

I'll work on a proposal for a new outline, and post it here when it's ready for commentary.

[larsoner]

Sounds good to me!

[agramfort]

👌

Sorry I could not make it yesterday

[hoechenberger]

ok! @drammock

[britta-wstnr]

For the logbook: We discussed this again at the last dev meeting with @drammock. Another thing that came up is that our contributor guide is 1) pretty long and hard to navigate and 2) hard to follow, for which I have opened another issue #11609 - linking this here as some of the documentation overlaps thematically.

[larsoner]

Bumping milestone to 1.5 since fix changes are easy to backport (don't even require a new point release)