Update troubleshooting guide for Spyder 6

doc/conf.py

@@ -302,14 +302,16 @@
 
 linkcheck_ignore = [
     # Virtual fragment ids
-    r"https://(www\.)?github\.com/.+/compare/.+#diff-.+",
+    r"https://(www\.)?github\.com/.+/.+/compare/.+#diff-.+",
+    r"https://(www\.)?github\.com/.+/.+/blob/.+/.+\.(md|rst)#.+",
     # Flaky
-    r"https://(www\.)?packages\.gentoo\.org/?.*",
-    r"https://(www\.)?software\.opensuse\.org/?.*",
-    r"https://(www\.)?packages\.ubuntu\.com/?.*",
-    r"https://(www\.)?github\.com/.+/commit/.+",
     r"https://(www\.)?figshare\.com/?.*",
+    r"https://(www\.)?github\.com/.+/commit/.+",
     r"https://(www\.)?opencollective\.(org|com)/?.*",
+    r"https://(www\.)?packages\.gentoo\.org/?.*",
+    r"https://(www\.)?packages\.ubuntu\.com/?.*",
+    r"https://(www\.)?ports\.macports\.org/port/.+/?",
+    r"https://(www\.)?software\.opensuse\.org/?.*",
     # Blocks GitHub Actions
     r"https://(www\.)?guru99\.com/?.*",
     r"https://(www\.)?(\w+\.)?reddit\.com/?.*",

doc/troubleshooting/basic-first-aid.rst

@@ -17,25 +17,29 @@ Recommended troubleshooting steps
 #. **Restart Spyder**, and try what you were doing before again.
 
 #. **Upgrade Spyder** to the latest release, and you might find your issue is resolved (along with new features, enhancements, and other bug fixes).
-   Minor releases come out every couple months, so unless you've updated recently, there is a good chance your version isn't the latest.
+   Bugfix releases come out every month or two, so unless you've updated recently, there is a good chance your version isn't the latest.
    You can find out with the :guilabel:`Check for updates` command under the :guilabel:`Help` menu.
 
    .. image:: /images/basic-first-aid/basic-first-aid-updates.png
       :alt: Spyder showing view internal console option
 
-   To perform the update with Conda (strongly recommended), from your terminal (or Anaconda Prompt on Windows) run:
+   Recent versions of Spyder using our recommended :ref:`install-standalone` will offer to automatically update themselves for you.
+   If using an older version of Spyder or a non-standalone build (e.g. installed with Pip or Conda), we recommend downloading and running our latest :ref:`install-standalone`.
 
-   .. code-block:: bash
-
-      conda update anaconda
-      conda update spyder
+   To perform the update with Conda, see the FAQ :ref:`update-conda`; to update with Pip use ``pip install --ugprade spyder``.
+   If that still doesn't work, we recommend updating Spyder's dependencies and environment, either by installing the latest version of Anaconda/Miniconda/Miniforge, or with the relevant "update all" command in your terminal (or Anaconda Prompt on Windows).
 
-#. **Update Spyder's dependencies and environment**, either by installing the latest version of your distribution (e.g. the recommended Anaconda), or with the relevant "update all" command in your terminal (or Anaconda Prompt on Windows).
    To get the latest stable version of everything using Conda, you can run:
 
-   .. code-block:: bash
+   .. code-block:: shell
+
+      conda update spyder qt pyqt spyder-kernels ipython ipykernel jupyter_client jupyter_core pyzmq
 
-      conda update qt pyqt spyder-kernels ipython ipykernel jupyter_client jupyter_core pyzmq
+   Or with Pip:
+
+   .. code-block:: shell
+
+      pip install --upgrade --upgrade-strategy "eager" spyder spyder-kernels ipython ipykernel jupyter_client jupyter_core pyzmq traitlets
 
 #. **Restart your machine**, in case the problem lies with a lingering process or another such issue.
 
@@ -51,13 +55,13 @@ Recommended troubleshooting steps
       This will reset your preferences, as well as any custom keyboard shortcuts or syntax highlighting schemes.
       If you particularly care about any of those, you should make a copy of the :file:`.spyder-py3` folder in your user home directory (:file:`C:/Users/YOUR_USERNAME` on Windows, :file:`/Users/YOUR_USERNAME` on macOS, or :file:`/home/YOUR_USERNAME` on Linux), and restore it afterwards if this doesn't solve the problem.
 
-#. **Try installing Spyder into a new Conda environment** (recommended) or ``virtualenv``/``venv``, and see if the issue reoccurs.
+#. **Try reinstalling Spyder** via our :ref:`install-standalone` (recommended), or in a fresh Conda/virtual environment, and see if the issue reoccurs.
 
-In your system terminal (or Anaconda Prompt on Windows), run the following commands to create an a fresh, clean environment and start Spyder in it:
+If using Conda to install Spyder (only recommended for advanced users needing plugin support), in your system terminal (or Anaconda Prompt on Windows), run the following commands to create a clean environment and start Spyder in it:
 
-.. code-block:: bash
+.. code-block:: shell
 
-   conda create -n spyder-env spyder -y
+   conda create -y -n spyder-env spyder numpy scipy pandas matplotlib cython sympy
    conda activate spyder-env
    spyder
 
@@ -81,20 +85,27 @@ Reinstalling Spyder
 
 If none of the previous steps solve your issue, you should do a full uninstall of Spyder by whatever means you originally installed it.
 
-For Anaconda, follow all the steps under Option B in the `Anaconda uninstall guide`_, delete the Anaconda directory wherever it was originally installed, and (on Windows) remove the :file:`%appdata%/python` directory if it exists.
+For Spyder's standalone installers, the uninstall mechanism varies depending on your operating system.
+On Windows, it can be removed via the entry under :guilabel:`Add or remove programs`.
+
+For Anaconda/Miniconda, follow all the steps under `Anaconda uninstall guide`_/`Miniconda uninstall guide`_.
+For Miniforge, follow the `Miniforge uninstall instructions`_ on macOS/Linux or remove it from :guilabel:`Add or remove programs` on Windows.
+Then, delete the Anaconda/Miniconda/Miniforge directory wherever it was originally installed, and (on Windows) remove the :file:`%appdata%/python` directory if it exists.
 
 .. image:: /images/basic-first-aid/basic-first-aid-app-data.gif
-   :alt: Deleting appdata/python directory
+   :alt: Deleting AppData/python directory
 
-Then, do a clean install of the latest version of the `Anaconda distribution`_ which is how we recommend you install Spyder and keep it up to date.
+Finally, do a clean install of the latest version of our :ref:`install-standalone`, which is how we recommend you install Spyder and keep it up to date.
 
 .. important::
 
-   While you are welcome to get Spyder working on your own by one of the many other means we offer, we are only able to provide individual support for install-related issues for users of the Anaconda distribution.
-   In particular, pip installation, while doable, is only really for experts, as there are many pitfalls involved and different issues specific to your setup, which is why we recommend using Conda whenever possible.
+   While you are welcome to get Spyder working on your own by one of the many other means we offer, we are only normally able to provide individual support for user-specific install issues related to our :ref:`install-standalone`.
+   In particular, managing your own installation via Conda or Pip can be easy to break, as there are many pitfalls involved and different issues specific to your setup, which is why we recommend using our standalone installers whenever possible.
    For further information, please visit our :ref:`install-guide`.
 
-.. _Anaconda uninstall guide: https://docs.anaconda.com/anaconda/install/uninstall/
+.. _Anaconda uninstall guide: https://www.anaconda.com/docs/getting-started/anaconda/uninstall
+.. _Miniconda uninstall guide: https://www.anaconda.com/docs/getting-started/miniconda/uninstall
+.. _Miniforge uninstall instructions: https://github.com/conda-forge/miniforge/blob/main/README.md#uninstall
 .. _Anaconda distribution: https://www.anaconda.com/products/distribution
 
 
@@ -112,21 +123,21 @@ If you manage to isolate the bug, report it to the last one it *doesn't* work in
 #. **Spyder** itself, of course!
    Make sure you can reproduce the error after closing and reopening it, if possible.
 
-#. **A bare QtConsole instance**, e.g. launched from Anaconda navigator or from the Anaconda Prompt/Terminal/command line (Windows/Mac/Linux) with ``jupyter qtconsole``.
+#. **A bare QtConsole instance**, e.g. launched from the system terminal (Anaconda Prompt, on Windows) with ``jupyter qtconsole``.
 
    .. image:: /images/basic-first-aid/basic-first-aid-qtconsole.png
       :alt: Anaconda navigator showing qtconsole
 
-   QtConsole is the GUI console backend Spyder depends on to run its code, so most issues involving Spyder's :ref:`panes-console` are actually something with QtConsole instead, and can be reported to their `issue tracker`_.
+   QtConsole is the GUI console backend Spyder depends on to run its code, so most issues involving Spyder's :ref:`panes-console` usually have something to do with QtConsole instead, and can be reported to the `QtConsole issue tracker`_.
 
-#. **An IPython command line shell**, launched with e.g. ``ipython`` from the Anaconda Prompt/Terminal/command line (Windows/Mac/Linux).
-   Reproducible bugs can be reported to their `Github page`_, though make sure to read their guidelines and docs first.
+#. **An IPython command line shell**, launched with e.g. ``ipython`` from system terminal (Anaconda Prompt, on Windows).
+   Reproducible bugs can be reported to the `IPython issue tracker`_, though make sure to read their guidelines and docs first.
 
-#. **A standard Python interpreter**, either run as a script file with ``python path/to/your/file.py`` or launched interactively with ``python`` from your Anaconda Prompt/Terminal/command line (Windows/Mac/Linux).
-   While it is not impossible that you've found Python bug, it is much more likely to be an issue with the code itself or a package you are using, so your best sources are the `Python docs`_ and the other resources listed above.
+#. **A standard Python interpreter**, either run as a script file with ``python path/to/your/file.py`` or launched interactively with ``python`` from your system terminal (Anaconda Prompt, on Windows).
+   While it is not impossible that you've found a Python bug, it is much more likely to be an issue with the code itself or a package you are using, so your best sources are the `Python docs`_ and the other resources listed above.
 
-.. _issue tracker: https://github.com/jupyter/qtconsole/issues/
-.. _Github page: https://github.com/ipython/ipython/issues
+.. _QtConsole issue tracker: https://github.com/jupyter/qtconsole/issues/
+.. _IPython issue tracker: https://github.com/ipython/ipython/issues
 .. _Python docs: https://www.python.org/doc/
 
 .. tip::

doc/troubleshooting/call-for-help.rst

@@ -58,9 +58,9 @@ Our `Google Group`_ is great for help-related questions, particularly those you
 Spyder website
 ~~~~~~~~~~~~~~
 
-The `Spyder site`_ contains basic information about the IDE and links to many other helpful resources.
+The `Spyder website`_ contains basic information about the IDE and links to other helpful resources.
 
-.. _Spyder site: https://www.spyder-ide.org/
+.. _Spyder website: https://www.spyder-ide.org/
 
 
 .. rst-class:: fabb fa-stack-overflow
@@ -141,7 +141,7 @@ Anaconda help
 
 The `Anaconda docs`_ site offers free community help and documentation for the Anaconda applications, installing the Anaconda distribution, and using the Conda package and environment manager; along with paid support options.
 
-.. _Anaconda docs: https://anaconda.cloud/support-center
+.. _Anaconda docs: https://www.anaconda.com/docs/
 
 
 .. rst-class:: fasb fa-flask
@@ -176,6 +176,6 @@ Project Jupyter
 Data Science Stack Exchange
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The `Data Science`_ site in Stack Exchange can be very useful for questions that relate more to data science than programming specifically.
+The `Data Science Stack Exchange site`_ can be very useful for questions that relate more to data science than programming specifically.
 
-.. _Data Science: https://datascience.stackexchange.com/
+.. _Data Science Stack Exchange site: https://datascience.stackexchange.com/

doc/troubleshooting/common-illnesses.rst

@@ -30,44 +30,11 @@ Spyder requires a supported version of the ``spyder-kernels`` package to be pres
 .. image:: /images/common-illnesses/common-illnesses-kernel-version.png
    :alt: Kernel version error dialog
 
-It is included by default with Anaconda, but if you want to run your code in another Python environment or installation, you'll need to make sure it's installed and updated to the latest version.
-
-Check the required version of spyder-kernels for your version of Spyder in the following table:
-
-.. table:: Spyder and Spyder-Kernels version compatibility
-
-   ==============   ==============
-   Spyder           Spyder-Kernels
-   ==============   ==============
-   4.0.0-4.0.1      1.8.1
-   4.1.0-4.1.2      1.9.0
-   4.1.3            1.9.1
-   4.1.4            1.9.3
-   4.1.5-4.1.6      1.9.4
-   4.2.0            1.10.0
-   5.0.0-5.0.5      2.0.5
-   5.1.0-5.1.5      2.1.3
-   5.2.0-5.2.1      2.2.0
-   5.2.2            2.2.1
-   5.3.0-5.3.3      2.3.3
-   5.4.0-5.4.3      2.4.3
-   ==============   ==============
-
-To do so, activate the environment, then install ``spyder-kernels``.
-If using Anaconda, open a terminal (Anaconda Prompt on Windows) and run:
+It is included by default in Spyder's own runtime environment, but if you want to run your code in your own Python environment or installation, you'll need to make sure it's installed and updated to the latest version.
 
-.. code-block:: bash
-
-   conda activate ENVIRONEMENT-NAME
-   conda install spyder-kernels=<VERSION>
-
-Otherwise, activate your environment by whatever means you created it, and execute:
-
-.. code-block:: bash
+To do so, open a system terminal, activate the Conda or virtual environment you want to use Spyder with, and then copy and paste the command Spyder generates for you (the ``conda`` command if in a Conda environment, or ``pip`` otherwise).
 
-   pip install spyder-kernels==<VERSION>
-
-For both of the previous commands, replace ``<VERSION>`` with the corresponding version in the table.
+Spyder 6.2+ will offer to update your Spyder-Kernels version automatically, if using Spyder through our recommended :ref:`install-standalone`.
 
 
 .. _troubleshooting-common-kernel-dependency:
@@ -78,26 +45,26 @@ Issue with another dependency
 If the kernel displays a long error traceback that mentions other packages like ``ipython``, ``ipykernel``, ``jupyter_client``, ``traitlets`` or ``pyzmq``, the problem may be an out of date or incompatible version of a dependency package.
 To fix this, activate the environment and update the key dependencies.
 
-In an Anaconda environment:
+In a Conda environment:
 
 .. code-block:: bash
 
-   conda activate ENVIRONMENT-NAME
+   conda activate ENVIRONMENT-NAME  # Replace with the name of your desired environment
    conda update spyder-kernels ipython ipykernel jupyter_client jupyter_core pyzmq traitlets
 
 Otherwise, activate your environment by whatever means you created it, and run:
 
 .. code-block:: bash
 
-   pip install -U spyder-kernels ipython ipykernel jupyter_client jupyter_core pyzmq traitlets
+   pip install --upgrade --upgrade-strategy "eager" spyder-kernels ipython ipykernel jupyter_client jupyter_core pyzmq traitlets
 
 
 .. _troubleshooting-common-kernel-error:
 
 AttributeError/ImportError
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Check the last few lines of the error message, and see if its an ``AttributeError`` or ``ImportError``, or refers to a file you created in your current working directory or your home folder (:file:`C:/Users/YOUR_USERNAME` on Windows, :file:`/Users/YOUR_USERNAME` on macOS, or :file:`/home/YOUR_USERNAME` on Linux).
+Check the last few lines of the error message, and see if it's an ``AttributeError`` or ``ImportError``, or refers to a file you created in your current working directory or your home folder (:file:`C:/Users/YOUR_USERNAME` on Windows, :file:`/Users/YOUR_USERNAME` on macOS, or :file:`/home/YOUR_USERNAME` on Linux).
 
 .. image:: /images/common-illnesses/common-illnesses-atribute-error.png
    :alt: Spyder's AtributeError dialog
@@ -117,8 +84,8 @@ To check the names of these modules, see the list in the `Python standard librar
 Completion/help not working
 ===========================
 
-To provide code completions, help and real-time analysis in the Editor, Spyder uses the Python Language Server (PyLS), an implementation of the Language Server Protocol specification used by VSCode, Atom and other popular editors/IDEs.
-Most help and completion issues lie outside of Spyder's control, and are either limitations with PyLS or the code that is being introspected, but some can be worked around.
+To provide code completions, help and real-time analysis in the Editor, Spyder uses the Python LSP Server (PyLSP), an implementation of the same Language Server Protocol specification supported by VSCode, Neovim and other popular editors/IDEs.
+Most help and completion issues lie outside of Spyder's control, and are either limitations with PyLSP or the code that is being introspected, but some can be worked around.
 
 
 .. _troubleshooting-common-completion-docstring:
@@ -155,7 +122,7 @@ LSP has stopped working
 ~~~~~~~~~~~~~~~~~~~~~~~
 
 Occasionally, especially after using Spyder for a while, code completion, help and analysis may stop working.
-If this is the case, you can check LSP status with the :guilabel:`LSP Python` item in Spyder's status bar at the bottom of the screen, and restart it by right-clicking it and selecting the :guilabel:`Restart Python Language Server` item.
+If this is the case, you can check LSP status with the :guilabel:`LSP: Python` item in Spyder's status bar at the bottom of the screen, and restart it by right-clicking it and selecting the :guilabel:`Restart Python Language Server` item.
 
 .. image:: /images/common-illnesses/common-illnesses-LSP-restart.png
    :alt: Spyder with LSP restart dialog
@@ -168,12 +135,7 @@ Spyder bug/dependency issue
 
 Given the variety of dependencies involved in making LSP work, an incompatible or out of date version in your environment can result in error messages, incomplete results, or help/analysis not working at all.
 
-To address this, first try updating Anaconda and Spyder as described in :ref:`troubleshooting-basic`.
-If the issue still isn't resolved, update the various relevant dependencies with:
-
-.. code-block:: bash
-
-   conda update python-language-server
+To address this, try updating Spyder as described in :ref:`troubleshooting-basic`.
 
 
 
@@ -188,15 +150,15 @@ Plugin Problems
 Plugin does not work at all
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If you have installed a Spyder plugin, but you can't see it, go to the :guilabel:`Panes` submenu of the :guilabel:`View` menu and select the plugin's name, which should make its pane visible.
-If you don't see the plugin there, select the :guilabel:`Dependencies` item under the :guilabel:`Help` menu and see if the plugin appears at the bottom.
+If you have installed a Spyder plugin, but you can't see it, go to the :guilabel:`Panes` submenu of the :guilabel:`Window` menu and select the plugin's name, which should make it visible if it contains a standalone pane.
+If you don't see the plugin there, select the :guilabel:`Plugins` section under Spyder's :guilabel:`Preferences` and see if it is listed there.
 
 .. image:: /images/common-illnesses/common-illnesses-plugins.png
    :alt: Dependencies dialog showing Unittest plugin
 
-If the plugin with the problem is not listed in the dependencies dialog, check that you installed it in the same environment as Spyder.
+If the plugin with the problem is not listed in the :guilabel:`Plugins` Preferences section, check that you installed it in the same environment as Spyder.
 If you have, then the problem may well be caused by a dependency issue.
-Test whether you can import the plug-in manually by opening a Python console in the same environment as Spyder and typing, for instance, ``import spyder_unittest`` to test the Spyder-Unittest` plug-in; this command should run without errors.
+Test whether you can import the plug-in manually by opening a Python console in the same environment as Spyder and typing, for instance, ``import spyder_unittest`` to test the Spyder-Unittest plug-in; this command should run without errors.
 
 If none of this helps you to resolve the problem, then continue to the next section.