install documentation cleanup

Open
#10,707 9 comments 0 reactions 1 assignee View on GitHub

@drammock is already working on this.

Since Oct 1, 2023.

Assessment

This issue has not been assessed yet.

Description

DOC

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

Dominant language
Python
Stars
3.5k
Forks
1.6k
Avg merge
1d 6h
Merged PRs (30d)
100

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from mne-tools/mne-python

All issues in mne-tools/mne-python

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.