Repository: mne-tools/mne-python

Issue:
RFC: installation process instructions
Based on some offline discussions with users, it may be time for some refinements to the install instructions. Specifically, we should make it clear that:

1. if they want to **update** mne-python, it's usually best to just `pip install -U mne`
2. if they want to update *everything in their environment* they should create a new environment instead of using the latest `environment.yml` to update an existing environment
3. (optional) given item 2, perhaps a "pro tip" would be to keep a list of other packages one installs into one's mne environment, to simplify the creation of new mne envs
4. consider revising our `environment.yml` to *not include* an env name, and update the recommended install command to `conda create --name mne --file environment.yml` instead.  The rationale here is that the current recommended command `conda env update --file environment.yml` implies that it can be used for updating

cc @NeuroLaunch @larsoner was there anything else from our discussion that I've forgotten to include here?


Discussion:
That sounds about right, I'm in favor of what will cause people the least pain. We should probably discuss at the next office hours if possible. I'm sure @hoechenberger has some ideas of where pain points have been -- hopefully they're mostly just around trying to *update* an env. If that's the case, to me the most important thing we can do is discourage people from doing this since we know it's pretty broken at the conda env.

Just a side note that whatever updates we make to the instructions we should backport to the stable docs, too, so that people landing there get the latest instructions.

That side note makes me think that separately, we should kill all installation instructions for < 0.23 and make them redirects, and probably add a step to the release instructions that says "replace the previous stable version's installation instructions with a HTML redirect".
Great idea! I've been onboarding lots of new users lately and the current instructions are great as long as they have nothing else installed. I personally did not know the correct way to update, so point 1 is great to know.

Just an FYI (probably not worth putting in the instructions, it might just confuse things). But I've given the https://github.com/mne-tools/mne-docker repo some love lately for this reason. With just a single command I can get people up and running to try MNE out and the environment is always in a working state. 
I think you guys got all the main points covered.  Thanks for spearheading this, Dan.
WDYT about moving all of this "first install Python, then run a bunch of commands" into an "expert" section for more ambitious and tech-savvy folks, and providing simple graphical standalone installer packages for ordinary users instead? I've started working on those:
https://github.com/hoechenberger/mne-installers/releases/tag/v2021.1-pre.3

It's working [but needs a bit of fine-tuning](https://github.com/hoechenberger/mne-installers/issues). Comes with more than MNE – includes MNE-BIDS and pybv and some other useful tools too. I've deployed the Linux package to one of our servers as a user was having trouble getting their `conda` installation to work, and so far it seems to provide a smooth experience. All installers allow for updating an existing installation (i.e., when a new installer is released, you can just run it without having to uninstall the previous version); and having multiple versions installed in parallel is also trivial (in fact, it was one of my main goals to allow for this particular use case). On Windows, "MNE-Python" will even be listed under "Apps & features" and can be uninstalled from there.

Because the installers are entirely self-contained, they make an offline install trivial, as nothing needs to be fetched from the web.

On Windows, we can optionally add Start menu entries.
@hoechenberger I like that you're working on providing that for users.  For now, since you say it still needs some fine-tuning, I'm hesitant to endorse it as an "official" install method in our docs.  I also want to be conservative about how much space we take up on people's hard drives...  not everybody will need the extra packages that you're bundling in there.  But when it's sufficiently fine-tuned I wouldn't object to adding it as a third option to [the quick-start page](https://mne.tools/dev/install/index.html)  WDYT?
@drammock No strong feeling here. I'm aiming for this to be tested & ready when we release 0.24 – for which I think we should start planning soon, the changelog has been growing quite a bit again since we released 0.23 :)

As for installation size – my goal was to provide something that will make installing and using MNE-Python much more of a no-brainer than it is now. I want to cover all the use cases I've seen among my colleagues; this includes using Pandas, BrainVision files, MNE-BIDS etc. If everything and a kitchen-sink is included, they only need to install this one thing and they're up and running. This currently takes up about 2.1 GB on my Mac – 0.4% of my 500 GB SSD storage, and at least one magnitude smaller than all datasets I'm working with. I really don't think storage space is a good argument in 2021, but I acknowledge that you have a different opinion. My reconciliation proposal is this: I'll try to finally get that `mne-base` `conda-forge`  package released (i.e., MNE-Python with a minimal number of dependencies) and then build "minimal" installers based on it – "Mini-MNE", if you will. WDYT?
> @drammock No strong feeling here. I'm aiming for this to be tested & ready when we release 0.24 – for which I think we should start planning soon, the changelog has been growing quite a bit again since we released 0.23 :)

last release was end of April, which means next release should be end of october.  Last year there was an "extra" december release, but personally I don't want us to make a habit of early or extra releases (it shortens deprecation times, for one thing).

> I really don't think storage space is a good argument in 2021

Fair point, although not everybody has new-ish computers and works with large-or-huge datasets.  I am also thinking more about bandwidth / download speed, perhaps moreso than actual space-on-disk.

> My reconciliation proposal is this: I'll try to finally get that `mne-base` `conda-forge` package released (i.e., MNE-Python with a minimal number of dependencies) and then build "minimal" installers based on it – "Mini-MNE", if you will. WDYT?

It would be wonderful if something like `conda create --name my_env_name "mne-base=0.23"` would "just work" and people never needed environment files.


> It would be wonderful if something like `conda create --name my_env_name "mne-base=0.23"` would "just work" and people never needed environment files.

But that's already working … If you do `conda create -n mne -c conda-forge mne`, you should end up with a (not minimalist, but still) working MNE environment with 3D support.
> But that's already working

why aren't we recommending that instead of `curl... environment.yaml; ... etc`?
I think those installers are a brilliant idea @hoechenberger, I'm going to try them out today. And I agree that hard disk space is probably not a big concern for average users. And that we are more likely to loose users from attempting and failing to install MNE than a large installer.
+1000 for `mne-base`!

Resolving patch:
diff --git a/doc/conf.py b/doc/conf.py
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -60,11 +60,10 @@
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
-# The short X.Y version.
-version = mne.__version__
 # The full version, including alpha/beta/rc tags.
-release = version
-
+release = mne.__version__
+# The short X.Y version.
+version = '.'.join(release.split('.')[:2])
 
 # -- General configuration ---------------------------------------------------
 
@@ -878,6 +877,16 @@ def reset_warnings(gallery_conf, fname):
     <i class="fa{cls} fa-{icon[3:] if fw else icon}{fw}"></i>
 '''
 
+# -- Dependency info ----------------------------------------------------------
+
+strip_chars = '=<>,"\''
+with open(os.path.join('..', 'setup.py'), 'r') as fid:
+    for line in fid:
+        if line.strip().startswith('python_requires='):
+            min_py = line.strip().split('=', maxsplit=1)[1].strip(strip_chars)
+
+prolog += f'\n.. |min_python_version| replace:: {min_py}\n'
+
 # -- website redirects --------------------------------------------------------
 
 # Static list created 2021/04/13 based on what we needed to redirect,


Test patch: