DOC: Reflow IDE doc (#12947)

Co-authored-by: Daniel McCloy <[email protected]>
mne-tools · Nov 5, 2024 · 2983d2a · 2983d2a
1 parent b3ecaab
commit 2983d2a
Show file tree

Hide file tree

Showing 5 changed files with 87 additions and 60 deletions.
diff --git a/doc/_static/js/set_installer_tab.js b/doc/_static/js/set_installer_tab.js
@@ -42,4 +42,14 @@ function setTabs() {
     uninstall_input.checked = true;
 }
 
+function setAlert() {
+    for (let button of document.querySelectorAll('.install-download-button')) {
+        button.addEventListener('click', function() {
+            alert = document.querySelectorAll('.install-download-alert')[0];
+            alert.style.display = 'block';
+        });
+    }
+}
+
 documentReady(setTabs);
+documentReady(setAlert);
diff --git a/doc/install/ides.rst b/doc/install/ides.rst
@@ -0,0 +1,55 @@
+.. _ide_setup:
+
+IDE integration (VSCode, Spyder, etc.)
+======================================
+
+Most users find it convenient to write and run their code in an `Integrated
+Development Environment`_ (IDE). Some popular choices for scientific
+Python development are:
+
+- `Visual Studio Code`_ (often shortened to "VS Code" or "vscode") is a
+  development-focused text editor that supports many programming languages in
+  addition to Python, includes an integrated terminal console, and has a rich
+  extension ecosystem. Installing
+  `Microsoft's Python Extension
+  <https://marketplace.visualstudio.com/items?itemName=ms-python.python>`__ is
+  enough to get most Python users up and running. VS Code is free and
+  open-source.
+
+- `Spyder`_ is a free and open-source IDE developed by and for scientists who
+  use Python. It can be installed via a
+  `standalone Spyder installer <https://docs.spyder-ide.org/current/installation.html#downloading-and-installing>`__.
+  To avoid dependency conflicts with Spyder, you should install ``mne`` in a
+  separate environment, as explained in previous sections or using our dedicated
+  installer. Then, instruct
+  Spyder to use the MNE-Python interpreter by opening
+  Spyder and `navigating to <https://docs.spyder-ide.org/current/faq.html#using-existing-environment>`__
+  :samp:`Tools > Preferences > Python Interpreter > Use the following interpreter`.
+
+- `PyCharm`_ is an IDE specifically for Python development that provides an
+  all-in-one solution (no extension packages needed). PyCharm comes in a
+  free and open-source Community edition as well as a paid Professional edition.
+
+For these IDEs, you'll need to provide the path to the Python interpreter you want it
+to use. If you're using the MNE-Python installers, on Linux and macOS opening the
+**Prompt** will display several lines of information, including a line that will read
+something like:
+
+.. code-block:: output
+
+   Using Python: /some/directory/mne-python_1.7.1_0/bin/python
+
+Altertatively (or on Windows), you can find that path by opening the Python interpreter
+you want to use (e.g., the one from the MNE-Python installer, or a ``conda`` environment
+that you have activated) and running::
+
+   >>> import sys
+   >>> print(sys.executable) # doctest:+SKIP
+
+This should print something like
+``C:\Program Files\MNE-Python\1.7.0_0\bin\python.exe`` (Windows) or
+``/Users/user/Applications/MNE-Python/1.7.0_0/.mne-python/bin/python`` (macOS).
+
+For Spyder, if the console cannot start because ``spyder-kernels`` is missing,
+install the required version in the conda environment. For example, with the
+environment you want to use activated, run ``conda install spyder-kernels``.
diff --git a/doc/install/index.rst b/doc/install/index.rst
@@ -74,6 +74,7 @@ Installing MNE-Python
     :hidden:
 
     installers
+    ides
     manual_install
     advanced
     check_installation

diff --git a/doc/install/installers.rst b/doc/install/installers.rst
@@ -21,7 +21,7 @@ Platform-specific installers
             :ref-type: ref
             :color: primary
             :shadow:
-            :class: font-weight-bold mt-3
+            :class: font-weight-bold mt-3 install-download-button
 
             |cloud-arrow-down| |ensp| Download for Linux
 
@@ -42,7 +42,7 @@ Platform-specific installers
             :ref-type: ref
             :color: primary
             :shadow:
-            :class: font-weight-bold mt-3
+            :class: font-weight-bold mt-3 install-download-button
 
             |cloud-arrow-down| |ensp| Download for macOS (Intel)
 
@@ -58,7 +58,7 @@ Platform-specific installers
             :ref-type: ref
             :color: primary
             :shadow:
-            :class: font-weight-bold mt-3
+            :class: font-weight-bold mt-3 install-download-button
 
             |cloud-arrow-down| |ensp| Download for macOS (Apple Silicon)
 
@@ -74,12 +74,29 @@ Platform-specific installers
             :ref-type: ref
             :color: primary
             :shadow:
-            :class: font-weight-bold mt-3
+            :class: font-weight-bold mt-3 install-download-button
 
             |cloud-arrow-down| |ensp| Download for Windows
 
         **Supported platforms:** Windows 10 and newer
 
+.. card::
+    :class-body: text-center
+    :class-card: install-download-alert hidden
+
+    .. We have to use a button-link here because button-ref doesn't properly nested parse the inline code
+
+    .. button-link:: ./ides.html
+        :ref-type: ref
+        :color: success
+        :shadow:
+        :class: font-weight-bold mt-3
+        :click-parent:
+
+        |rocket| Go to IDE Setup
+
+    Once installation completes, **set up your IDE**!
+
 .. raw:: html
 
    <script async="async" src="../_static/js/update_installer_version.js"></script>

diff --git a/doc/install/manual_install.rst b/doc/install/manual_install.rst
@@ -93,59 +93,3 @@ tips and tricks for special situations (servers, notebooks, CUDA, installing
 the development version, etc). The :ref:`contributing` has additional
 installation instructions for (future) contributors to MNE-Python (e.g, extra
 dependencies for running our tests and building our documentation).
-
-.. _ide_setup:
-
-Python IDE integration
-======================
-
-Most users find it convenient to write and run their code in an `Integrated
-Development Environment`_ (IDE). Some popular choices for scientific
-Python development are:
-
-- `Visual Studio Code`_ (often shortened to "VS Code" or "vscode") is a
-  development-focused text editor that supports many programming languages in
-  addition to Python, includes an integrated terminal console, and has a rich
-  extension ecosystem. Installing
-  `Microsoft's Python Extension
-  <https://marketplace.visualstudio.com/items?itemName=ms-python.python>`__ is
-  enough to get most Python users up and running. VS Code is free and
-  open-source.
-
-- `Spyder`_ is a free and open-source IDE developed by and for scientists who
-  use Python. It can be installed via a
-  `standalone Spyder installer <https://docs.spyder-ide.org/current/installation.html#downloading-and-installing>`__.
-  To avoid dependency conflicts with Spyder, you should install ``mne`` in a
-  separate environment, as explained in previous sections or using our dedicated
-  installer. Then, instruct
-  Spyder to use the MNE-Python interpreter by opening
-  Spyder and `navigating to <https://docs.spyder-ide.org/current/faq.html#using-existing-environment>`__
-  :samp:`Tools > Preferences > Python Interpreter > Use the following interpreter`.
-
-- `PyCharm`_ is an IDE specifically for Python development that provides an
-  all-in-one solution (no extension packages needed). PyCharm comes in a
-  free and open-source Community edition as well as a paid Professional edition.
-
-For these IDEs, you'll need to provide the path to the Python interpreter you want it
-to use. If you're using the MNE-Python installers, on Linux and macOS opening the
-**Prompt** will display several lines of information, including a line that will read
-something like:
-
-.. code-block:: output
-
-   Using Python: /some/directory/mne-python_1.7.1_0/bin/python
-
-Altertatively (or on Windows), you can find that path by opening the Python interpreter
-you want to use (e.g., the one from the MNE-Python installer, or a ``conda`` environment
-that you have activated) and running::
-
-   >>> import sys
-   >>> print(sys.executable) # doctest:+SKIP
-
-This should print something like
-``C:\Program Files\MNE-Python\1.7.0_0\bin\python.exe`` (Windows) or
-``/Users/user/Applications/MNE-Python/1.7.0_0/.mne-python/bin/python`` (macOS).
-
-For Spyder, if the console cannot start because ``spyder-kernels`` is missing,
-install the required version in the conda environment. For example, with the
-environment you want to use activated, run ``conda install spyder-kernels``.