Merge branch 'spyder-ide:master' into master

.pre-commit-config.yaml

@@ -168,7 +168,7 @@ repos:
 
 # Lint RST
 - repo: https://github.com/sphinx-contrib/sphinx-lint
-  rev: 'v0.6.1'
+  rev: v0.8.1
   hooks:
   - id: sphinx-lint
     name: Lint RST

STYLEGUIDE.md

@@ -41,8 +41,8 @@ Must (not), should (not), recommended, suggested, may, and can generally follow
 * L2 Headings for section heads: Use ========= with overline; 3 blank lines before them
 * L3 headings for subheads: Use ~~~~~~; 2 blank lines
 * L4 Headings for sub-subheads if truly necessary: Use ---------; 1 blank line; keep to a minimum (consider a flatter structure or breaking into multiple files)
-* Related components at the bottom: L2 heading; bullets; try for 2-4 links if included
-* All files with Related components should contain at least one L2 section; if only one, can be entitled Overview
+* Related panes at the bottom: L2 heading; bullets; try for 2-4 links if included
+* All files with ``Related panes`` should contain at least one L2 section; if only one, can be entitled Overview
 * Typically, for files with multiple sections or longer than one page, a summary section of a few lines length is helpful before the first section, summarizing the functionality discussed in the section and its purpose
 * Name of component/topic should be in first sentence, Title Case, bold on first use
 

doc/Makefile

@@ -2,7 +2,7 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    = -n -W --keep-going
+SPHINXOPTS    = -n -W --keep-going --color
 SPHINXBUILD   = sphinx-build
 SPHINXPROJ    = Spyder
 SOURCEDIR     = .

doc/_static/css/custom_styles.css

@@ -354,3 +354,13 @@ a.dropdown-link:focus {
   color: #fff;
   text-decoration: none;
 }
+
+/* Temporary fix for invisible heading :before blocking clicks */
+
+h2::before,
+h3::before,
+h4::before,
+h5::before,
+h6::before {
+  pointer-events: none;
+}

doc/faq.rst

@@ -105,7 +105,7 @@ Running Spyder
    Try it `here`_.
 
    .. _Binder: https://mybinder.org/
-   .. _here: https://mybinder.org/v2/gh/spyder-ide/spyder/5.x?urlpath=/desktop
+   .. _here: https://mybinder.org/v2/gh/spyder-ide/binder-environments/spyder-stable?urlpath=git-pull%3Frepo%3Dhttps%253A%252F%252Fgithub.com%252Fspyder-ide%252FSpyder-Workshop%26urlpath%3Ddesktop%252F%26branch%3Dmaster
 
 
 .. dropdown:: Q: What are the system requirements for Spyder? How resource-intensive is it?
@@ -176,87 +176,64 @@ Using Spyder
       :start: 306
 
 
+.. _using-existing-environment:
+
 .. dropdown:: Q: How do I get Spyder to work with my existing Python packages/environment?
    :container: + dropdown-id-using-existing-environment
 
-   To work with an existing environment in Spyder, you need to change Spyder’s default Python interpreter.
-   To do so, click the name of the current environment in the status bar, and then click :guilabel:`Change default environment in Preferences`.
-
-   .. image:: /images/faq/faq-change-environment.png
-      :alt: Change default environment in Preferences option in status bar
+   To work with an existing environment in Spyder, change the default Python interpreter for new :doc:`/panes/ipythonconsole`\s to point to this environment.
 
-   This will open the :guilabel:`Preferences` dialog in the :guilabel:`Python interpreter` section.
+   To do so, open the :guilabel:`Python interpreter` section of Spyder's preferences (:menuselection:`Tools --> Preferences`, or :menuselection:`Spyder --> Preferences` on macOS).
    Here, select the option :guilabel:`Use the following Python interpreter`, and use the dropdown below to select your preferred environment.
-   If its not listed, use the text box or the :guilabel:`Select file` button to enter the path to the Python interepreter you want to use.
-   See the :doc:`/panes/ipythonconsole` for more information.
+   If it's not listed, see :ref:`the note below <faq-env-not-listed>`.
 
    .. image:: /images/faq/faq-python-interpreter.png
       :alt: Preferences showing changing Python interpreter
 
-   Click :guilabel:`Restart kernel` in the :guilabel:`Consoles` menu for this change to take effect.
+   .. _faq-env-not-listed:
+
+   .. note::
+
+      If you installed Miniconda (or another Conda-based distribution) to a non-default path, or are using a virtual environment managed by a tool other than ``pyenv``, your environments likely won't be listed.
+
+      Instead, use the text box or the :guilabel:`Select file` button to enter the path to the Python interpreter you want to use.
+      You can find this path by activating the venv or Conda env you want to use in your terminal (Anaconda Prompt on Windows), and running the command:
+
+      .. code-block:: shell
+
+         python -c "import sys; print(sys.executable)"
+
+   Finally, click :guilabel:`Restart kernel` in the :guilabel:`Consoles` menu for this change to take effect.
+   If ``spyder-kernels`` is not already installed, the :doc:`/panes/ipythonconsole` will display instructions on how to install the right version.
+   Execute the given command in your terminal (the Anaconda Prompt on Windows) with the environment activated, and finally restart the kernel once more.
 
 
+.. _using-packages-installer:
+
 .. dropdown:: Q: How do I install Python packages to use within Spyder if I downloaded Spyder from the standalone installers?
    :container: + dropdown-id-using-packages-installer
 
-   Watch our video on using additional modules or follow the instructions below it.
+   Watch our video on using additional packages or follow the instructions below.
 
    .. youtube:: i7Njb3xO4Fw
       :height: 360
       :width: 640
       :align: left
       :start: 306
 
-   If you want to use other modules in Spyder that don't come with our installer, you need to install `Miniconda`_ (**only if you don't have Anaconda or Miniconda yet!**).
-   For Spyder to recognize it, the installation should be done in one of the following default paths:
-
-   .. table::
-
-       +------------------------------------+---------------------------------+
-       |Windows                             | macOS                           |
-       +====================================+=================================+
-       |C:\\Users\\<username>\\Anaconda     | /Users/<username>/opt/anaconda  |
-       +------------------------------------+---------------------------------+
-       |C:\\Users\\<username>\\Miniconda    | /Users/<username>/opt/miniconda |
-       +------------------------------------+---------------------------------+
-       |C:\\Users\\<username>\\Anaconda3    | /Users/<username>/opt/anaconda3 |
-       +------------------------------------+---------------------------------+
-       |C:\\Users\\<username>\\Miniconda3   | /Users/<username>/opt/miniconda3|
-       +------------------------------------+---------------------------------+
-       |C:\\Anaconda                        |   /opt/anaconda                 |
-       +------------------------------------+---------------------------------+
-       |C:\\Miniconda                       |   /opt/miniconda                |
-       +------------------------------------+---------------------------------+
-       |C:\\Anaconda3                       |   /opt/anaconda3                |
-       +------------------------------------+---------------------------------+
-       |C:\\Miniconda3                      |   /opt/miniconda3               |
-       +------------------------------------+---------------------------------+
-       |C:\\ProgramData\\Anaconda           |                                 |
-       +------------------------------------+---------------------------------+
-       |C:\\ProgramData\\Miniconda          |                                 |
-       +------------------------------------+---------------------------------+
-       |C:\\ProgramData\\Anaconda3          |                                 |
-       +------------------------------------+---------------------------------+
-       |C:\\ProgramData\\Miniconda3         |                                 |
-       +------------------------------------+---------------------------------+
+   If you want to use other packages in Spyder that don't come with our installer, you need to have your own Python distribution installed; we recommend `Miniconda`_ or another Conda-based option.
+   For Spyder to recognize it automatically, you should use a Conda-based distribution with its default install path.
 
    .. _Miniconda: https://docs.conda.io/en/latest/miniconda.html
 
-   Then, you need to create a new conda environment with the modules that you want to use with Spyder and include ``spyder-kernels`` in it. For example, if you want to use ``scikit-learn``, open your terminal or the Anaconda prompt on Windows and run the following commands:
-
-   .. code-block:: bash
-
-      conda create -n spyder-env -y
-      conda activate spyder-env
-      conda install spyder-kernels scikit-learn -y
-
-   Finally, you need to connect Spyder to this environment by changing Spyder’s default Python interpreter. To do this, click the name of the current environment in the status bar, and then click :guilabel:`Change default environment in Preferences`.
+   Create a new conda environment containing ``spyder-kernels`` and the packages that you want to use.
+   For example, if you want to use ``scikit-learn``, open your terminal (or Anaconda prompt on Windows) and run the following command:
 
-   This will open the :guilabel:`Preferences` dialog in the :guilabel:`Python interpreter` section. Here, select the option :guilabel:`Use the following Python interpreter`, and use the dropdown below to select your preferred environment. If it is not listed, use the text box or the :guilabel:`Select file` button to enter the path to the Python interpreter you want to use.
+   .. code-block:: shell
 
-   **Your new environment will only be listed here if you installed Miniconda (or Anaconda) in the default path as shown in the table above.**
+      conda create -n my-env -c conda-forge spyder-kernels scikit-learn
 
-   Click :guilabel:`Restart kernel` in the :guilabel:`Consoles` menu for this change to take effect.
+   Finally, connect Spyder to this ``my-env`` environment by changing Spyder's default Python interpreter, following the instructions in :ref:`the above answer <using-existing-environment>`.
 
 
 .. dropdown:: Q: How do I reset Spyder's preferences to the defaults?
@@ -291,12 +268,12 @@ Using Spyder
 .. dropdown:: Q: How do I use plugins with Spyder (e.g. Spyder-Notebook, Spyder-Terminal, Spyder-Unittest)?
    :container: + dropdown-id-using-plugins
 
-   Spyder plugins are available in the ``spyder-ide`` conda channel.
+   Spyder plugins are available in the ``conda-forge`` conda channel.
    To install one, type on the command line (or Anaconda Prompt on Windows):
 
    .. code-block:: bash
 
-      conda install -c spyder-ide <PLUGIN>
+      conda install -c conda-forge <PLUGIN>
 
    Replace ``<PLUGIN>`` with the name of the plugin you want to use.
    For more information on a specific plugin, go to the its repository:
@@ -435,7 +412,7 @@ About Spyder
    If you use Spyder with the Anaconda distribution, they `recently changed`_ their `Terms of Service`_ to add restrictions on large (> 200 employee) for-profit companies using Anaconda on a large scale.
    However, these terms only apply to the package infrastructure (the full Anaconda distribution and the ``defaults`` conda channel).
    Instead, you can simply download the similar `Miniforge distribution`_, which is 100% open source and identical to full Anaconda (aside from not bundling the Python packages installed by default in the Anaconda ``base`` environment, which we recommend you avoid using anyway given any problems here can break your whole installation).
-   Then, simply install the packages you need (including Spyder, if you aren't using our recommended :ref:`standalone_installers_ref`) with ``conda`` as you usually do.
+   Then, simply install the packages you need (including Spyder, if you aren't using our recommended :ref:`install-standalone`) with ``conda`` as you usually do.
    Miniforge will automatically use the community-maintained Conda-Forge repository, which has a much wider variety of packages and is generally more up to date than the Anaconda equivalent, in addition to being free of any commercial restrictions.
    For more, see our :doc:`/installation`.