diff --git a/doc/debugging.rst b/doc/debugging.rst index 65f5f438f..898dc1380 100644 --- a/doc/debugging.rst +++ b/doc/debugging.rst @@ -1,45 +1,62 @@ +######### Debugging -========= +######### -Debugging in Spyder is supported thanks to the following Python modules: - -* `pdb`: the Python debugger, which is included in Python standard library. - -* `winpdb`: a graphical frontend to `pdb`, which is an external package - (in the :doc:`editor`, press F7 to run `winpdb` on the currently edited - script). +**Debugging** in Spyder is supported through integration with the enhanced ``ipdb`` debugger in the :doc:`ipythonconsole`. +This allows breakpoints and the execution flow to be viewed and controlled right from the Spyder GUI, as well as with all the familiar IPython console commands. .. image:: images/debugging/debugging_console.png :align: center :alt: A Spyder IPython console window, showing the ipdb debugger in action -Debugging with pdb ------------------- +| + + +=================== +Debugging with ipdb +=================== + +Spyder offers the following debugging features integrated into the native GUI: + +.. image:: images/menu/menu_debug.png + :align: right + :width: 50% + :alt: Spyder's debug menu, showing options to set, show and clear breakpoints, and control debugger execution flow -The Python debugger is partly integrated in Spyder: +* Multiple means of setting and clearing normal and conditional breakpoints for any line in a file opened in the :doc:`editor`. -* Breakpoints may be defined in the :doc:`editor`. + * By selecting the respective option from the Debug menu. + * Through pressing a configurable keyboard shortcut (:kbd:`F12` for normal, or :kbd:`Shift-F12` for conditional breakpoints by default). + * By double-clicking to the left of the line number in an open file. + * With an ``ipdb.set_trace()`` statement in your code (after ``import`` ing ``pdb``). + * Interactively, using the ``b`` command in an ``ipdb`` session. - * Simple breakpoints can be set from the Run menu, by keyboard shortcut - (F12 by default), or by double-click to the left of line numbers - in the :doc:`editor`. - * Conditional breakpoints can also be set from the Run menu, by - keyboard shortcut (Shift+F12 by default), or by Shift+double-click - to the left of line numbers in the :doc:`editor`. +.. image:: images/debugging/breakpoints_standard.png + :align: right + :width: 50% + :alt: Spyder's Breakpoints panel, with a number of examples showing file, line number and an optional condition + +* A :guilabel:`Breakpoints` pane, listing the file, line, and condition (if any) of every breakpoint defined (:menuselection:`&Debug --> List breakpoints`, or :kbd:`Ctrl-Shift-B` by default). + +* Full GUI control over debugger execution from the :guilabel:`Debug` menu, :guilabel:`Debug toolbar` and via configurable keyboard shortcuts, along with the standard ``ipdb`` console commands. .. image:: images/debugging/debugging_condbreakpoint.png - :align: center - :alt: Inset of Spyder Editor, with breakpoint set and condition dialog open + :align: right + :width: 50% + :alt: Inset of Spyder's Editor, with a breakpoint set and the condition dialog open + +* Highlighting of the current frame (debugging step) in the :doc:`editor`. + +* The ability to access and edit local and global variables at each breakpoint through the :doc:`variableexplorer`, and run many commands in the :doc:`ipythonconsole`. -* The current frame (debugging step) is highlighted in the :doc:`editor`. -* At each breakpoint, globals may be accessed through - the :doc:`variableexplorer`. +For a comprehensive but accessible introduction to ``pdb``/``ipdb``, consult Steve Ferg's excellent online guide, `Debugging in Python`_. -For a simple, yet quite complete introduction to `pdb`, you may read this: -http://pythonconquerstheuniverse.wordpress.com/category/python-debugger/ +.. _Debugging in Python: https://pythonconquerstheuniverse.wordpress.com/2009/09/10/debugging-in-python/ -Related plugins: +Related components +~~~~~~~~~~~~~~~~~~ * :doc:`editor` * :doc:`ipythonconsole` +* :doc:`variableexplorer` diff --git a/doc/editor.rst b/doc/editor.rst index 8cdf17fd6..d161c2594 100644 --- a/doc/editor.rst +++ b/doc/editor.rst @@ -1,11 +1,9 @@ +###### Editor -====== +###### -Spyder's text editor is a multi-language editor with features such as syntax -coloring, code analysis (real-time code analysis powered by `pyflakes` and -advanced code analysis using `pylint`), introspection capabilities such as -code completion, calltips and go-to-definition features (powered by `rope`), -function/class browser, horizontal/vertical splitting features, etc. +Spyder's multi-language **Editor** integrates a number of powerful tools right out of the box for an easy to use, efficient editing experience. +The Editor's key features include syntax highlighting (``pygments``); real-time code and style analysis (``pyflakes`` and ``pycodestyle``); on-demand completion, calltips and go-to-definition features (``rope`` and ``jedi``); a function/class browser, horizontal and vertical splitting, and much more. .. image:: images/editor/editor_split_horizontal.png :align: center @@ -13,36 +11,38 @@ function/class browser, horizontal/vertical splitting features, etc. | -Function/class/method browser and horizontal/vertical splitting feature: +:guilabel:`Outline Explorer` (function/class/method browser) and horizontal/vertical splitting capabilities: |outline| |split| -.. |outline| image:: images/editor/outline_standard.png +.. |outline| + image:: images/editor/outline_standard.png :width: 209px :alt: Spyder outline panel, showing the functions/classes/methods in a file -.. |split| image:: images/editor/editor_split_vertical.png +.. |split| + image:: images/editor/editor_split_vertical.png :width: 422px :alt: A Spyder editor window, split vertically into two independent panes | -Code analysis with `pyflakes`: +Real-time code and style analysis with ``pyflakes`` and ``pycodestyle``: .. image:: images/editor/editor_inset_code_analysis.png - :align: center :alt: A snippit of code in the Spyder Editor, showing code style warnings +| -How to define a code cell --------------------------- +=================== +Defining code cells +=================== -A "code cell" is a concept similar to MATLAB's "cell" (except that there is -no "cell mode" in Spyder), i.e. a block of lines to be executed at once in the -current interpreter (Python or IPython). Every script may be divided in as -many cells as needed. +A "code cell" in Spyder is a block of lines, typically in a script, that can be easily executed all at once in the current doc:`ipythonconsole`. +This is much like a "cell" in MATLAB (except without any need to enable a "cell mode", since in Spyder, cells are detected automatically). +You can divide your scripts into as many cells as needed, or none at all—the choice is yours. .. image:: images/editor/editor_standard.png :align: center @@ -50,14 +50,20 @@ many cells as needed. | -Cells are separated by lines starting with: +You can separate cells by lines starting with either: -* `#%%` (standard cell separator) -* `# %%` (standard cell separator, when file has been edited with Eclipse) -* `# ` (IPython notebook cell separator) +* ``#%%`` (standard cell separator) +* ``# %%`` (standard cell separator, when file has been edited with Eclipse) +* ``# `` (IPython notebook cell separator) -Related plugins: +Providing a description to the right of the separator will give that cell its own name in the :guilabel:`Outline Explorer`. + + +Related components +~~~~~~~~~~~~~~~~~~ -* :doc:`ipythonconsole` * :doc:`fileexplorer` * :doc:`findinfiles` +* :doc:`ipythonconsole` +* :doc:`projects` +* :doc:`pylint` diff --git a/doc/fileexplorer.rst b/doc/fileexplorer.rst index da2b9be55..8a34c0857 100644 --- a/doc/fileexplorer.rst +++ b/doc/fileexplorer.rst @@ -1,18 +1,20 @@ +############# File Explorer -============= +############# -The file explorer pane is a file/directory browser allowing the user to open -files with the internal editor or with the appropriate application (Windows -only). +The **File Explorer** pane is a built-in filesystem and directory browser allowing you to view and filter files and their properties, open them with the :doc:`editor` or an external tool, and perform common management tasks (varies by platform). .. image:: images/file_explorer/file_explorer_standard.png - :align: center :alt: Spyder File Explorer panel, showing a tree view of files and metadata | -Context menus may be used to run a script, open a terminal window or run a -Windows explorer window (Windows only): + +========================== +Performing file operations +========================== + +You can use context menus to access a number of functions on a per-file and per-directory basis, including running scripts, creating, renaming, moving, editing or deleting files, performing basic operations with ``git``, and (on Windows) opening an external file explorer. .. image:: images/file_explorer/file_explorer_contextmenu_new.png :align: center @@ -20,7 +22,10 @@ Windows explorer window (Windows only): | -Related plugins: -* :doc:`ipythonconsole` +Related components +~~~~~~~~~~~~~~~~~~ + * :doc:`editor` +* :doc:`findinfiles` +* :doc:`projects` diff --git a/doc/findinfiles.rst b/doc/findinfiles.rst index abd816cb0..16259019e 100644 --- a/doc/findinfiles.rst +++ b/doc/findinfiles.rst @@ -1,15 +1,29 @@ -Find in files -============= +############# +Find in Files +############# -The *Find in Files* plugin provides text search in whole directories or -`mercurial` repositories (or even in PYTHONPATH) with regular expression -support for maximum search customization. +The **Find in Files** pane allows to you perform full-text, recursive content search in a user-defined scope, with advanced features to filter your results. .. image:: images/find_in_files/find_in_files_inprogress.png :alt: Spyder Find in Files panel, with search results shown per-file | -Related plugins: + +======================= +Choosing search options +======================= + +The :guilabel:`Find in Files` tool allows you to select from a number of options to enable searches as broad or refined as you need: + +* To enable case sensitivity, controlling whether matches are returned with a different case than your search text, toggle the :guilabel:`Aa` button on. +* To parse your search string as a regular expression, allowing for highly expressive search queries, toggle the :guilabel`Gear` button on. +* To exclude certain filenames, types, or directories from your search, use the :guilabel:`Exclude:` text box, which can similarly be parsed as a regular expression with the :guilabel:`Gear` button to its right. +* To select whether to search in a specific file, in the current working directory, in a new or previously-used custom directory, or even in entire :doc:`projects`, use the :guilabel:`Search In` menu. + + +Related components +~~~~~~~~~~~~~~~~~~ * :doc:`editor` +* :doc:`fileexplorer` diff --git a/doc/help.rst b/doc/help.rst index 2e250e9e7..b1cbd358f 100644 --- a/doc/help.rst +++ b/doc/help.rst @@ -1,43 +1,46 @@ +#### Help -==== +#### -The help plugin works together with the :doc:`ipythonconsole` and the -:doc:`editor`: it shows automatically documentation available when the -user is instantiating a class or calling a function (pressing the left -parenthesis key after a valid function or class name triggers a call -in the help pane). +You can use the **Help** pane to find, render and display rich documentation for any object with a docstring, including modules, classes, functions and methods. +Help can be retrieved both by static analysis of open files in the :doc:`editor`, or by dynamically inspecting an object in an :doc:`ipythonconsole`. -Note that this automatic link may be disabled by pressing the "Lock" button -(at the top right corner of the window). +You can trigger help by manually entering the object's name into the :guilabel:`Object` box, pressing the configurable help shortcut (:kbd:`Ctrl-I` by default), or even automatically if desired when on typing a left parenthesis (``(``) after a function or method name. +Automatic help can be individually enabled for both the :guilabel:`Editor` and the :guilabel:`Console` under :menuselection:`Preferences --> Help --> Automatic Connections`, and turned on and off dynamically via the :guilabel:`lock` icon in the top right corner of the :guilabel:`Help` pane. -Of course, one can use the documentation viewer directly by entering an object -name in the editable combo box field, or by selecting old documentation requests -in the combo box. -Rich text mode: +======================== +Understanding help modes +======================== + +You can use the options menu (:guilabel:`Gear` icon) in the top right of the :guilabel:`Help` pane to toggle the help display mode. + +:guilabel:`Rich Text` mode renders the object's docstrings with ``Sphinx``: .. image:: images/help/help_standard.png :alt: Spyder Help panel, displaying rich text docs for the DataFrame class | -Plain text mode: +:guilabel:`Plain Text` mode displays the docstring without formatting: .. image:: images/help/help_plain.png :alt: Spyder Help panel, displaying plain text docs for the DataFrame class | -Sometimes, when docstrings are not available or not sufficient to document the -object, the documentation viewer can show the source code (if available, i.e. -if the object is pure Python): +:guilabel:`Show Source` displays the docstring inline with the code for the selected object, or any Python portion of it (if the object is not pure Python). +This can be useful when docstrings are not available or insufficient to document the object: .. image:: images/help/help_source_code.png :alt: Help panel showing part of the docstring and source code for DataFrame | -Related plugins: -* :doc:`ipythonconsole` +Related components +~~~~~~~~~~~~~~~~~~ + * :doc:`editor` +* :doc:`ipythonconsole` +* :doc:`onlinehelp` diff --git a/doc/historylog.rst b/doc/historylog.rst index 3f8e79d21..c194da3a5 100644 --- a/doc/historylog.rst +++ b/doc/historylog.rst @@ -1,14 +1,30 @@ -History log -=========== +########### +History Log +########### -The history log plugin collects command histories of Python/IPython interpreters -or command windows. +With the **History Log** pane, you can view an automatically de-duplicated, time-stamped list of every command you enter into any connected :doc:`ipythonconsole`. .. image:: images/history_log/history_log_menu.png :alt: Spyder History Log, displaying a list of previously executed commands | -Related plugins: + +===================== +Using the History Log +===================== + +Navigating the :guilabel:`History Log` is very straightforward. +Each session is marked by a date and time-stamp, making it easy to remember when you executed a certain command. +Statements can be selected and copied from the context menu or with the normal system shortcuts. +Just like in the editor, highlighting a word or phrase displays all other occurrences, and full syntax highlighting is also supported. +Finally, the top-right options menu (:guilabel:`Gear` icon) allows you to toggle soft-wrapping of long lines (:guilabel:`Wrap lines`), and set the number of commands the :guilabel:`History Log` should remember (:guilabel:`History`). + +The :guilabel:`History Log` is stored in the :file:`.spyder-py3` (Python 3) or :file:`spyder` (Python 2) directory in your user home folder (by default, :file:`C:/Users/{username}` on Windows, :file:`/Users/{username}` for macOS, and typically :file:`/home/{username}` on GNU/Linux). +You might need to show invisible files in order to see it on a non-Windows operating system. + + +Related components +~~~~~~~~~~~~~~~~~~ * :doc:`ipythonconsole` diff --git a/doc/images/debugging/breakpoints_standard.png b/doc/images/debugging/breakpoints_standard.png new file mode 100644 index 000000000..0ca3070df Binary files /dev/null and b/doc/images/debugging/breakpoints_standard.png differ diff --git a/doc/images/dialog/dialog_new_project.png b/doc/images/dialog/dialog_new_project.png new file mode 100644 index 000000000..000360fd6 Binary files /dev/null and b/doc/images/dialog/dialog_new_project.png differ diff --git a/doc/images/internal_console/internal_console_contextmenu_settings.png b/doc/images/internal_console/internal_console_contextmenu_settings.png new file mode 100644 index 000000000..b6f6b48a7 Binary files /dev/null and b/doc/images/internal_console/internal_console_contextmenu_settings.png differ diff --git a/doc/images/menu/menu_debug.png b/doc/images/menu/menu_debug.png new file mode 100644 index 000000000..e82633c5c Binary files /dev/null and b/doc/images/menu/menu_debug.png differ diff --git a/doc/index.rst b/doc/index.rst index e93250b00..5e2efff10 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -1,5 +1,6 @@ -Spyder - Documentation -====================== +##################################################### +Spyder: The Scientific Python Development Environment +##################################################### | @@ -9,24 +10,25 @@ Spyder - Documentation | -Spyder is the Scientific Python Development Environment: +Spyder is a powerful scientific environment written in Python, for Python, and designed by and for scientists, engineers and data analysts. +It features a unique combination of the advanced editing, analysis, debugging, and profiling functionality of a comprehensive development tool with the data exploration, interactive execution, deep inspection, and beautiful visualization capabilities of a scientific package. +Furthermore, Spyder offers built-in integration with many popular scientific packages, including `NumPy`_, `SciPy`_, `Pandas`_, `IPython`_, `QtConsole`_, `Matplotlib`_, `SymPy`_, and more. -* A powerful interactive development environment for the Python language with - advanced editing, interactive testing, debugging and introspection features -* A numerical computing environment thanks to the support of `IPython` - (an enhanced interactive Python interpreter) and popular Python libraries - such as `NumPy` (linear algebra), `SciPy` (signal and image processing) - and `matplotlib` (interactive 2D/3D plotting). +.. _NumPy: https://www.numpy.org/ +.. _SciPy: https://www.scipy.org/ +.. _Pandas: https://pandas.pydata.org/ +.. _IPython: https://ipython.org/ +.. _QtConsole: https://qtconsole.readthedocs.io/en/stable/ +.. _Matplotlib: https://matplotlib.org/ +.. _SymPy: https://www.sympy.org/en/index.html -Spyder may also be used as a library providing powerful console-related widgets -for your PyQt-based applications -- for example, it may be used to integrate a -debugging console directly in the layout of your graphical user interface. +Beyond its many built-in features, Spyder's abilities can be extended even further via its plugin system and API. +Spyder can also be used as a PyQt5 extension library, allowing you to build upon its functionality and embed its components, such as the interactive console, in your own software. -For more information about Spyder and to download the latest version, please -see the relevant links in the sidebar. - -Contents: +======== +Contents +======== .. toctree:: :maxdepth: 2 @@ -37,18 +39,13 @@ Contents: options editor ipythonconsole - debugging variableexplorer help - projects + debugging pylint + projects fileexplorer - historylog findinfiles onlinehelp + historylog internalconsole - -Indices and tables: - -* :ref:`genindex` -* :ref:`search` diff --git a/doc/installation.rst b/doc/installation.rst index f0d2afc4f..5ba3599d2 100644 --- a/doc/installation.rst +++ b/doc/installation.rst @@ -1,129 +1,136 @@ +############ Installation -============ +############ -Spyder is quite easy to install on Windows, Linux and macOS; just read the -following instructions with care. +Spyder is relatively easy to install on Windows, Linux and macOS. +Just make sure to read and follow these instructions with care. This section explains how to install the latest stable release of Spyder. -If you prefer testing the development version, please use the -``bootstrap`` script (see next section). - -If you run into problems, before posting a report, -*please* consult our comprehensive -`Troubleshooting Guide `_ -and search the `issue tracker `_ -for your error message and problem description, as these methods are known to -fix or at least isolate the vast majority of install-related problems. +If you prefer testing the development version, please use the :ref:`boostrap script` instead. + +If you run into problems, before posting a report, *please* consult our comprehensive `Troubleshooting Guide`_ and search the `issue tracker`_ for your error message and problem description, as these methods generally fix or isolate the great majority of install-related complaints. Thanks! +.. _Troubleshooting Guide: https://github.com/spyder-ide/spyder/wiki/Troubleshooting-Guide-and-FAQ +.. _issue tracker: https://github.com/spyder-ide/spyder/issues -The Easy/Recommended Way: Anaconda ----------------------------------- -Spyder is included in the `Anaconda `_ -Python distribution, which comes with everything you need to get started in -an all-in-one package. +====================================== +Installing with Anaconda (recommended) +====================================== -This is the easiest way to install Spyder for any of our supported platforms, -and the way we recommend to avoid unexpected issues we aren't able to -help you with. If in doubt, you should install via this method; -it generally has the least likelihood of potential pitfalls for non-experts, -and we may be able to provide limited assistance if you do run into trouble. +Spyder is included by default in the `Anaconda`_ +Python distribution, which comes with everything you need to get started in an all-in-one package. +.. _Anaconda: https://www.anaconda.com/download/ -The Harder Way: Alternative distributions ------------------------------------------ +This is the easiest way to install Spyder for any of our supported platforms, and the way we recommend to avoid unexpected issues we aren't able to help you with. +If in doubt, you should install via this method; it generally has the least likelihood of potential pitfalls for non-experts, and we may be able to provide limited assistance if you do run into trouble. -**Important Note:** While we offer alternative Spyder installation options -for users who desire them, we currently lack the resources to offer individual -assistance for problems specific to installing via these alternative distributions. -Therefore, we recommend you switch to Anaconda if you encounter installation -issues you are unable to solve on your own. -Windows -~~~~~~~ +=========================================== +Installing with an alternative distribution +=========================================== -Spyder is also included in the `WinPython `_ -scientific Python distribution, although some users have reported bugs specific -to it. You can use it immediately after installing, just like with Anaconda. +.. caution:: -macOS -~~~~~ + While we offer alternative Spyder installation options for users who desire them, we currently lack the resources to offer individual assistance for problems specific to installing via these alternative distributions. + Therefore, we recommend you switch to Anaconda if you encounter installation issues you are unable to solve on your own. -Thanks to the `*MacPorts* project `_, Spyder can be -installed using its ``port`` package manager; however, it may be out of date -or have MacPorts-specific issues outside of Spyder's control. -There are `several versions`__ available from which you can choose from. +Install on Windows +~~~~~~~~~~~~~~~~~~ -__ http://www.macports.org/ports.php?by=name&substr=spyder +Spyder is also included in the `WinPython`_ scientific Python distribution, although it doesn't include Anaconda's convenient ``conda`` package and environment manager like Anaconda. +You can use it immediately after installing, just like with Anaconda. - .. warning:: +.. _WinPython: https://winpython.github.io/ - It is known that the MacPorts version of Spyder is raising this error: - ``ValueError: unknown locale: UTF-8``, which doesn't let it start correctly. - To fix it you will have to set these environment variables in your - ``~/.profile`` (or ``~/.bashrc``) manually:: +Install on macOS +~~~~~~~~~~~~~~~~ - export LANG=en_US.UTF-8 - export LC_ALL=en_US.UTF-8 +Thanks to the `MacPorts project`_, Spyder can be installed using its ``port`` package manager; however, the included Spyder version may be out of date or have MacPorts-specific issues outside of Spyder's control. -| +.. _MacPorts project: https://www.macports.org/ -GNU/Linux -~~~~~~~~~ +There are `several versions`_ available from which you can choose. -Please refer to the `Requirements`_ section to see what other packages you -might need. +.. _several versions: https://www.macports.org/ports.php?by=name&substr=spyder -**Ubuntu**: +.. attention:: -Using the official package manager: ``sudo apt-get install spyder``. + The MacPorts version of Spyder may currently be raising ``ValueError: unknown locale: UTF-8``, which doesn't let it start correctly. + To fix it you will have to set these environment variables in your :file:`~/.profile` (or :file:`~/.bashrc`) file manually: - .. note:: + .. code-block:: bash - This package could be slightly outdated. If you find that is the case, - please use the Debian package mentioned below. + export LANG=en_US.UTF-8 + export LC_ALL=en_US.UTF-8 -**Debian Unstable**: +Install on GNU/Linux +~~~~~~~~~~~~~~~~~~~~ -Using the package manager: ``sudo apt-get install spyder`` +Please refer to the `Requirements`_ to see what other packages you might need. -The Spyder's official Debian package is available `here`__ -__ http://packages.debian.org/fr/sid/spyder. +Ubuntu +------ +Using the official package manager: -**Other Distributions** +.. code-block:: bash -Spyder is also available in other GNU/Linux distributions, like + sudo apt-get install spyder + +.. note:: + + This package could be slightly outdated. If you find that is the case, please use the Debian package mentioned below. + + +Debian Unstable +--------------- + +Using the package manager: + +.. code-block:: bash + + sudo apt-get install spyder3 -* `Archlinux `_ +Spyder's official Debian package is available on the `Debian package repository`_. -* `Fedora `_ +.. _Debian package repository: https://packages.debian.org/unstable/spyder3 -* `Gentoo `_ -* `openSUSE `_ +Other Distributions +------------------- -* `Mageia `_ +Spyder is also available in other GNU/Linux distributions, like + +* `Arch Linux`_ +* `Fedora`_ +* `Gentoo`_ +* `openSUSE`_ +* `Mageia`_ + +.. _Arch Linux: https://aur.archlinux.org/packages/?K=spyder +.. _Fedora: https://fedoraproject.org/wiki/Spyder +.. _Gentoo: https://packages.gentoo.org/packages/dev-python/spyder +.. _openSUSE: https://software.opensuse.org/package/spyder3 +.. _Mageia: https://madb.mageia.org/package/show/name/spyder -Please refer to your distribution's documentation to learn how to install it -there. +Please refer to your distribution's documentation to learn how to install Spyder. -| +================================== +Installing with pip (experts only) +================================== -The Expert Way: Installing with pip ------------------------------------ +.. warning:: -**Warning:** While this installation method is a viable option for -experienced users, installing Spyder (and other SciPy stack packages) -with `pip` can lead to a number of tricky issues. While you are welcome -to try this on your own, we unfortunately do not have the resources to help you -if you do run into problems, except to recommend using Anaconda instead. + While this installation method is a viable option for experienced users, installing Spyder (and other SciPy stack packages) with ``pip`` can lead to a number of tricky issues. + While you are welcome to try this on your own, we unfortunately do not have the resources to help you if you do run into problems, except to recommend you use Anaconda instead. Requirements @@ -131,196 +138,165 @@ Requirements The requirements to run Spyder are: -* `Python `_ 2.7 or >=3.3 +* `Python `_ 2.7 or >=3.3 -* `PyQt5 `_ >=5.2 or - `PyQt4 `_ >=4.6.0 - (PyQt5 is recommended). +* `PyQt5 `_ >=5.5 -* `Qtconsole `_ >=4.2.0 -- for an - enhanced Python interpreter. +* `Qtconsole `_ >=4.2.0 -- for an enhanced Python interpreter. -* `Rope `_ >=0.9.4 and - `Jedi `_ >=0.11.0 -- for code completion, - go-to-definition and calltips on the Editor. +* `Rope `_ >=0.9.4 and `Jedi `_ >=0.11.0 -- for code completion, go-to-definition and calltips in the Editor. -* `Pyflakes `_ -- for real-time - code analysis. +* `Pyflakes `_ -- for real-time code analysis. -* `Sphinx `_ -- for the Help pane rich text mode - and to get our documentation. +* `Sphinx `_ -- for the Help pane rich text mode and to get our documentation. -* `Pygments `_ >=2.0 -- for syntax highlighting and code - completion in the Editor of all file types it supports. +* `Pygments `_ >=2.0 -- for syntax highlighting and code completion in the Editor of all file types it supports. -* `Pylint `_ -- for static code analysis. +* `Pylint `_ -- for static code analysis. -* `Pycodestyle `_ -- for style analysis. +* `Pycodestyle `_ -- for style analysis. -* `Psutil `_ -- for memory/CPU usage in the status - bar. +* `Psutil `_ -- for memory/CPU usage in the status bar. -* `Nbconvert `_ -- to manipulate Jupyter notebooks - on the Editor. +* `Nbconvert `_ -- to manipulate Jupyter notebooks on the Editor. -* `Qtawesome `_ >=0.4.1 -- for an icon theme based on - FontAwesome. +* `Qtawesome `_ >=0.4.1 -- for an icon theme based on FontAwesome. -* Pickleshare -- To show import completions on the Editor and Consoles. +* `Pickleshare `_ -- To show import completions in the Editor and Consoles. -* `PyZMQ `_ -- To run introspection services on the - Editor asynchronously. +* `PyZMQ `_ -- To run introspection services in the Editor asynchronously. -* `QtPy `_ >=1.2.0 -- To run Spyder with PyQt4 or - PyQt5 seamlessly. +* `QtPy `_ >=1.2.0 -- To run Spyder with different Qt bindings seamlessly. -* `Chardet `_ >=2.0.0-- Character encoding auto-detection - in Python. +* `Chardet `_ >=2.0.0-- Character encoding auto-detection in the Editor. -* `Numpydoc `_ Used by Jedi to get return types for - functions with Numpydoc docstrings. +* `Numpydoc `_ Used by Jedi to get return types for functions with Numpydoc docstrings. -* `Cloudpickle `_ Serialize variables in the - IPython kernel to send them to Spyder. +* `Cloudpickle `_ Serialize variables in the IPython kernel to send them to Spyder. Optional modules ~~~~~~~~~~~~~~~~ -* `Matplotlib `_ >=1.0 -- for 2D and 3D plotting - in the consoles. +* `Matplotlib `_ >=1.0 -- for 2D and 3D plotting in the consoles. -* `Pandas `_ >=0.13.1 -- for view and editing DataFrames - and Series in the Variable Explorer. +* `Pandas `_ >=0.13.1 -- for viewing and editing Series and DataFrames in the Variable Explorer. -* `Numpy `_ -- for view and editing two or three - dimensional arrays in the Variable Explorer. +* `Numpy `_ -- for viewing and editing two or three dimensional arrays in the Variable Explorer. -* `Sympy `_ >=0.7.3 -- for working with symbolic mathematics - in the IPython console. +* `Sympy `_ >=0.7.3 -- for working with symbolic mathematics in the IPython console. -* `Scipy `_ -- for importing Matlab workspace files in - the Variable Explorer. +* `Scipy `_ -- for importing Matlab workspace files in the Variable Explorer. -* `Cython `_ >=0.21 -- Run Cython files or Python files that - depend on Cython libraries in the IPython console. +* `Cython `_ >=0.21 -- to run Cython files or Python files that depend on Cython libraries in the IPython console. Installation procedure ~~~~~~~~~~~~~~~~~~~~~~ -You can install Spyder with the ``pip`` package manager, which comes by -default with most Python installations. -Before installing Spyder itself by this method, you need to acquire the -`Python programming language `_ +You can install Spyder with the ``pip`` package manager, which comes by default with most Python installations. +Before installing Spyder itself by this method, you need to acquire the `Python`_ programming language. + +.. _Python: https://www.python.org/ Then, to install Spyder and its other dependencies, run ``pip install spyder``. -You may need to separately install a Qt binding with ``pip`` if running Python 2; -PyQt5 is strongly recommended though the legacy PyQt4 is also still supported. +You may need to install a Qt binding (PyQt5) separately with ``pip`` if running under Python 2. Run without installing ~~~~~~~~~~~~~~~~~~~~~~ -You can execute Spyder without installing it first by following these steps: +You can execute Spyder from source without installing it first by the following procedure: -#. Unzip the source package available for download on the - `Spyder Github repo `_ - (or clone from Github, see the next section) +#. Unzip the source package available for download on the `Spyder Github repository`_ (or :ref:`clone it from Github`) #. Change current directory to the unzipped directory -#. Run Spyder with the command ``python bootstrap.py`` -#. (*Optional*) Build the documentation with ``python setup.py build_doc``. +#. Install Spyder's requirements with: -This is especially useful for beta-testing, troubleshooting and helping develop -Spyder itself. + .. code-block:: bash -| + pip install -r requirements/requirements.txt +#. Run Spyder with the command: -Updating Spyder ---------------- + .. code-block:: bash -You can update Spyder by: + python bootstrap.py -* Updating Anaconda (recommended), WinPython, MacPorts, or - through your system package manager, if you installed via those options. +.. _Spyder Github repository: https://github.com/spyder-ide/spyder - With Anaconda, just run (in Anaconda Prompt if on Windows) - ``conda update spyder`` - to update Spyder specifically, and - ``conda update anaconda`` - to update the rest of the distribution, as desired. +This is especially useful for beta-testing, troubleshooting and helping develop Spyder itself. -* If you installed Spyder via the advanced/crossplatform method, - ``pip``, run - ``pip install --upgrade spyder`` - .. note:: +=============== +Updating Spyder +=============== + +If you installed Spyder through Anaconda (recommended), WinPython, MacPorts, or your system package manager, update using those same methods. +With Anaconda, just run (in Anaconda Prompt if on Windows) ``conda update anaconda`` to update the distribution as a whole and ``conda update spyder`` to update Spyder specifically. - This command will also update all Spyder dependencies +If you installed Spyder via the advanced/cross-platform method, ``pip``, run ``pip install --upgrade spyder``. +This command will also update all Spyder dependencies, so we recommend you use an isolated ``virtualenv`` or ``venv`` environment to avoid any potential unintended effects on other installed packages. -| +.. _install-from-source: -Installing the development version ----------------------------------- +============================== +Installing a development build +============================== If you want to try the next Spyder version before it is released, you can! -You may want to do this for fixing bugs in Spyder, adding new -features, learning how Spyder works or just getting a taste of it. -For more information, please see the CONTRIBUTING.md document included -with the Spyder source or on Github, or for further detail consult the -`online development wiki `_ . +You may want to do this for fixing bugs in Spyder, adding new features, learning how Spyder works or just getting a taste of what the IDE can do. +For more information, please see the `CONTRIBUTING.md document`_ included with the Spyder source or on Github, and for further detail consult the `Spyder development wiki`_. + +.. _CONTRIBUTING.md document: https://github.com/spyder-ide/spyder/blob/master/CONTRIBUTING.md +.. _Spyder development wiki: https://github.com/spyder-ide/spyder/wiki -To do so: +In summary: -#. Install Spyder `requirements`_ +#. Install the Spyder `requirements`_. The recommended and easiest way to do this is with ``conda``: - ``conda install spyder`` - then - ``conda remove spyder`` - This installs all of Spyder's dependencies into the environment along with - the stable/packaged version of Spyder itself, and then removes the latter. + .. code-block:: bash + + conda install spyder + conda remove spyder + + This installs all of Spyder's dependencies into the environment along with the stable/packaged version of Spyder, and then removes Spyder itself. -#. Install `Git `_, a powerful - source control management tool. +#. Install `Git`_, a powerful source control management tool. #. Clone the Spyder source code repository with the command: - ``git clone https://github.com/spyder-ide/spyder.git`` + .. code-block:: bash -#. Run Spyder with the ``bootstrap.py`` script from within the cloned directory: - ``python bootstrap.py`` + git clone https://github.com/spyder-ide/spyder.git -#. To keep your repository up-to-date, run +#. Run Spyder with the :file:`bootstrap.py` script from within the cloned :file:`spyder/` directory: - ``git pull`` + .. code-block:: bash - inside the cloned directory. + python bootstrap.py -#. (*Optional*) If you want to read the documentation, you must build it first - with the command +#. To keep your repository up-to-date, run ``git pull`` inside the cloned directory. - ``python setup.py build_doc`` +.. _Git: https://git-scm.com/downloads -| +=============== +Additional help +=============== -Help and support ----------------- +* For a comprehensive guide to spyder troubleshooting, including installation issues, read our `Troubleshooting Guide and FAQ`_. +* For general information about Spyder and its ecosystem, see our `main website`_. +* For bug reports and feature requests, check out our `Github repository`_. +* For development-oriented help and information, consult our `Github wiki`_. +* For discussions and help requests, you can subscribe to our `Google Group`_. +* For quick questions and to chat with the dev team, stop by our `Gitter chatroom`_. -* For a comprehensive guide to spyder troubleshooting, including - installation issues, read our `Troubleshooting Guide and FAQ - `_. -* For general information about Spyder and its ecosystem, see our - `main website `_. -* For bug reports and feature requests, check out our - `Github repository `_. -* For development-oriented help and information, consult our - `Github wiki `_. -* For discussions and help requests, you can subscribe to our - `Google Group `_. -* For quick questions and to chat with the dev team, stop by our - `Gitter chatroom `_. +.. _Troubleshooting Guide and FAQ: https://github.com/spyder-ide/spyder/wiki/Troubleshooting-Guide-and-FAQ +.. _main website: https://www.spyder-ide.org/ +.. _Github repository: https://github.com/spyder-ide/spyder/ +.. _Github wiki: https://github.com/spyder-ide/spyder/wiki +.. _Google Group: https://groups.google.com/group/spyderlib +.. _Gitter chatroom: https://gitter.im/spyder-ide/public diff --git a/doc/internalconsole.rst b/doc/internalconsole.rst index 726f5cf86..8658605fe 100644 --- a/doc/internalconsole.rst +++ b/doc/internalconsole.rst @@ -1,17 +1,34 @@ +################ Internal Console -================ +################ -The **Internal Console** is dedicated to Spyder internal debugging or may be -used as an embedded Python console in your own application. -All the commands entered in the internal console are executed in the same -process as Spyder's, but the Internal Console may be executed in a separate -thread (this is optional and for example this is not the case in Spyder itself). +You can use the **Internal Console** to control and debug Spyder itself, or as an embedded Python console in your own application. .. image:: images/internal_console/internal_console_standard.png :alt: Spyder Internal Console, with error messages and command output shown | -The internal console support the following features: -* Code completion and calltips +================== +Supported features +================== + +The :guilabel:`Internal Console` supports code completion and calltips, just like a normal :doc:`ipythonconsole`, along with a number of GUI selection, line-wrapping, buffer, and clear/copy/paste options. +You can toggle and customize these behaviors under :guilabel:`Internal console settings` from the context menu. +Additionally, you can use a number of special commands to open a file in a Spyder or external editor, edit or remove variables, run scripts or system commands, get help, and more. +See the :guilabel:`Help` dialog in the context menu for more details on these. + +.. image:: images/internal_console/internal_console_contextmenu_settings.png + :alt: Spyder Internal Console, showing context menu with settings options + +| + +By default, all the commands entered in the :guilabel:`Internal Console` are executed in the same process as Spyder's. +However, you can run the :guilabel:`Internal Console` in a separate thread by passing ``--multithread`` as one of Spyder's :doc:`options` on launch. + + +Related components +~~~~~~~~~~~~~~~~~~ + +* :doc:`ipythonconsole` diff --git a/doc/ipythonconsole.rst b/doc/ipythonconsole.rst index 8ccff96d0..4b635255c 100644 --- a/doc/ipythonconsole.rst +++ b/doc/ipythonconsole.rst @@ -1,14 +1,9 @@ +############### IPython Console -=============== +############### -The **IPython Console** is where you may enter, interact with and visualize -data inside a command interpreter. All the commands entered in the console are -executed in a separate process, thus allowing the user to interrupt any -process at any time. Each console implements a full two-process -`IPython `_ session where -a lightweight front-end interface connects to a full IPython kernel on the -back end. Visit the IPython project website for full documentation of -IPython's many features. +The **IPython Console** allows you to execute commands and enter, interact with and visualize data inside any number of fully featured `IPython `_ interpreters. +Each console is executed in a separate process, allowing you to run scripts, interrupt execution and restart or terminate a shell without affecting the others or Spyder itself, and easily test your code in a clean environment without disrupting your primary session. .. image:: images/console/console_standard.png :align: center @@ -17,79 +12,82 @@ IPython's many features. | -From the Consoles menu, Spyder can launch **IPython Console** -instances that attach to kernels that are managed -by Spyder itself or it can connect to external kernels that are managed -by IPython Qt Console sessions or the IPython Notebook. + +======================= +Connecting to a console +======================= + +Spyder can launch new ``IPython`` instances itself, through "Open an IPython console" under the :guilabel:`Consoles` menu, the :guilabel:`IPython Console` pane menu or its context menu (:kbd:`Ctrl-T` by default), to take advantage of the full suite of Spyder's features. +Each console implements a robust two-process ``IPython`` session, with a lightweight front-end interface connected to a full kernel back end. +Additionally, you can connect to external kernels managed by QtConsole sessions or the Jupyter Notebook, through the :guilabel:`Connect to an existing kernel` dialog under the same menus, which support many of Spyder's advanced capabilities. .. image:: images/console/console_menu.png :align: center - :alt: Spyder IPython Console as above, except with the options menu open - + :alt: Spyder IPython Console as above, with the options menu open | -When "Connect to an existing kernel" is selected, Spyder prompts for the -kernel connection file details: +When :guilabel:`Connect to an existing kernel` is selected, Spyder prompts for the connection details: .. image:: images/console/console_dialog_connect.png :align: center - :alt: Connect to kernel dialog requesting path and connection details + :alt: Connect to kernel dialog, requesting path and connection details | -**IPython Consoles** that are attached to kernels that were created by -Spyder support the following features: + +================== +Supported features +================== + +Any :guilabel:`IPython Console` in Spyder, internally or externally created, supports additional features including: .. image:: images/console/console_completion.png :align: right :width: 50% :alt: Spyder IPython Console, with a popup list of code completion guesses -* Code completion and calltips -* Variable explorer with GUI-based editors for arrays, lists, - dictionaries, strings, etc. -* Debugging with standard Python debugger (`pdb`): at each breakpoint - the corresponding script is opened in the :doc:`editor` at the breakpoint - line number -* User Module Reloader (see below) +* Automatic code completion +* Real-time function calltips +* Debugging toolbar integration for launching the debugger and controlling execution flow -**IPython Consoles** attached to external kernels support a smaller feature -set: +Spyder-created consoles support even more advanced capabilities, such as: -* Code completion -* Debugging toolbar integration for launching the debugger and sending - debugging step commands to the kernel. Breakpoints must be set manually - from the console command line. +* The :doc:`variableexplorer`, with GUI-based editors for many built-in and third-party Python objects +* Full GUI integration with the enhanced ``IPython`` debugger, ``ipdb``, including viewing and setting normal and conditional breakpoints interactively in any file, a :guilabel:`Breakpoints` pane, and following along with execution flow in the in the :doc:`editor` (see the :doc:`debugging` documentation for more details) +* The :ref:`User Module Reloader `, which can automatically re-import modified packages and files +* Inline display of ``Matplotlib`` graphics, if the ``Inline`` backend is selected under :menuselection:`Preferences --> IPython console --> Graphics --> Graphics backend` +For information on the features, commands and capabilities built into ``IPython`` itself, see the `IPython documentation`_. -Reloading modules: the User Module Reloader (UMR) -------------------------------------------------- +.. _IPython documentation: https://ipython.readthedocs.io/en/stable/overview.html -When working with Python scripts interactively, one must keep in mind that -Python import a module from its source code (on disk) only when parsing the -first corresponding import statement. During this first import, the byte code -is generated (.pyc file) if necessary and the imported module code object is -cached in `sys.modules`. Then, when re-importing the same module, this cached -code object will be directly used even if the source code file (.py[w] file) -has changed meanwhile. -This behavior is sometimes unexpected when working with the Python interpreter -in interactive mode, because one must either always restart the interpreter -or remove manually the .pyc files to be sure that changes made in imported -modules were taken into account. +.. _umr-section: -The User Module Reloader (UMR) is a Spyder console's exclusive feature that -forces the Python interpreter to reload modules completely when executing -a Python script. +=================================== +Using UMR to reload changed modules +=================================== -For example, when UMR is turned on, one may test complex applications -within the same Python interpreter without having to restart it every time -(restart time may be relatively long when testing GUI-based applications). +When working with scripts and modules in an interactive session, Python only loads a module from its source file once, the first time it is ``import``ed. +During this first ``import``, the bytecode (``.pyc`` file) is generated if necessary and the imported module object is cached in ``sys.modules``. +If you subsequently re-import the module anytime in the same session without Spyder, this cached code object will be used even if its source code (``.py{w}`` file) has changed in the meantime. +While efficient for final production code, this behavior is often undesired when working interactively, such as when analyzing data or testing your own modules. +In effect, you're left with no way to update or modify any already-imported modules, aside from manually removing the relevant ``.pyc`` files, or restarting the console entirely. +Fortunately, in Spyder, there's an easy solution: the :guilabel:`User Module Reloader` (UMR), a Spyder-exclusive feature that, when enabled, automatically reloads modules right in the existing ``IPython`` shell whenever they are modified and re-imported, without any of the downsides of the above workarounds. +Even better, Spyder also loads the ``%autoreload`` magic by default into any kernels it starts, allowing changes in already imported modules to be automatically picked up the as soon as the modified file is saved, without any additional user action. +With UMR enabled, you can test complex applications within the same ``IPython`` interpreter without having to restart it every time you make a change, saving large amounts of manual tedium and long restart times. +Or, if you're analyzing data step by step using your own custom libraries, you can easily add or tweak a function in the latter and see the results reflected in the former, all without the overhead of reloading the data and re-running your whole script to restore your session to the same point. -Related plugins: +UMR is enabled by default, and will do its work automatically without user intervention, although it will provide you with a red ``Reloaded modules:`` message in the console listing the files it has refreshed when it activates. If desired, you can turned it and the message on and off, and prevent specific modules from being reloaded, under :menuselection:`Preferences --> Python interpreter --> User Module Reloader (UMR)`. -* :doc:`help` + +Related components +~~~~~~~~~~~~~~~~~~ + +* :doc:`debugging` * :doc:`editor` -* :doc:`fileexplorer` +* :doc:`help` +* :doc:`historylog` +* :doc:`variableexplorer` diff --git a/doc/onlinehelp.rst b/doc/onlinehelp.rst index 9c42367d1..26b519caa 100644 --- a/doc/onlinehelp.rst +++ b/doc/onlinehelp.rst @@ -1,9 +1,8 @@ -Online help -=========== +########### +Online Help +########### -The online help plugin provides an internal web browser to explore dynamically -generated Python documentation on installed module, including your own modules -(this documentation is provided by a pydoc server running in background). +The **Online Help** pane provides a built-in web browser to explore dynamically generated Python documentation on installed modules—including your own—rendered by a ``pydoc`` server running in the background. .. image:: images/online_help/online_help_standard.png :width: 570px @@ -11,6 +10,21 @@ generated Python documentation on installed module, including your own modules | -Related plugins: + +===================== +Using the Online Help +===================== + +Enter the name of the item you'd like documentation on in the :guilabel:`Module or package` field, or the :guilabel:`Get` field, to load its doc directly. +Or, if you're not sure of the name of the object you want help on, or are looking for a specific keyword, use the :guilabel:`Search` field to get a list of results. +You can view and re-run previous searches with the drop-down menu or the :kbd:`Down Arrow` key in the :guilabel:`Module or package field`, navigate previous pages with the forward and back buttons (top left, left and right arrows), and go back to the homepage with the home button (house icon top left) or the ``Module Index`` link top right. + +Perform a realtime search within a page's content with the :guilabel:`Find` button (magnifying glass icon top left) or :kbd:`Ctrl-F`, navigate through matches with the Up and Down buttons, and make matching case sensitive with the :guilabel:`Aa` button. +You can use the zoom in/out buttons (:guilabel:`-` and :guilabel:`+`, top right), to change the font size to suit your preferences. +Finally, to cancel searching or page loading, click the stop button (red :guilabel:`X`, top right) and to reload the help content you're seeing to the most current version on disk (such as when you change your package's documentation), hit the refresh button (circular arrows, top right). + + +Related components +~~~~~~~~~~~~~~~~~~ * :doc:`help` diff --git a/doc/options.rst b/doc/options.rst index 4fe7dd7d7..a0a52aaad 100644 --- a/doc/options.rst +++ b/doc/options.rst @@ -1,23 +1,22 @@ -Command line options -==================== +#################### +Command Line Options +#################### -Spyder's command line options are the following: +Spyder's command line options include the following: Options: - -h, --help show this help message and exit - --new-instance Run a new instance of Spyder, even if the single - instance mode has been turned on (default) - --defaults Reset configuration settings to defaults - --reset Remove all configuration files! - --optimize Optimize Spyder bytecode (this may require - administrative privileges) + -h, --help Show this help message and exit + --new-instance Run a new Spyder instance, even if single instance mode is enabled + --defaults Reset Spyder settings file to the defaults + --reset Remove all configuration files and reset to defaults! + --optimize Optimize Spyder bytecode (may require administrative privileges) -w WORKING_DIRECTORY, --workdir=WORKING_DIRECTORY - Default working directory + Set the default working directory --hide-console Hide parent console window (Windows) - --show-console (Deprecated) Does nothing, now the default behavior is to show the console - --multithread Internal console is executed in another thread - (separate from main application thread) - --profile Profile mode (internal test, not related with Python - profiling) + --show-console (Deprecated) Does nothing, now the default behavior + --multithread Execute the Internal Console in separate thread from the application + --profile Profile mode (internal test, not related to Python profiling) --window-title=WINDOW_TITLE - String to show in the main window title + String to show in the window title, to identify the Spyder instance + -p OPEN_PROJECT, --project=OPEN_PROJECT + Path that contains an Spyder project to open on startup diff --git a/doc/overview.rst b/doc/overview.rst index 3ecbfafd0..ac030aa28 100644 --- a/doc/overview.rst +++ b/doc/overview.rst @@ -1,5 +1,6 @@ +######## Overview -======== +######## .. image:: images/mainwindow/mainwindow_custom_1610.png :align: center @@ -7,92 +8,99 @@ Overview | -Spyder is a Python development environment with the following key features: +Spyder, the Scientific Python Development Environment, includes the following key features: -Key features: +* :doc:`editor`: + + * Customizable syntax highlighting themes + * :doc:`debugging` breakpoints and conditional breakpoints (through ``ipdb`` integration) + * Interactive execution: Run line/selection, run cell, run file, re-run and debug + * Run configuration settings: + + * Working directory selection + * Command line options + * Run in Current/dedicated/external console choice + * Automatically clear variables or enter debugging + + * :guilabel:`Outline Explorer`: Navigate cells, functions, classes, blocks, and more + * Real-time code introspection features (powered by ``rope`` and ``jedi``): -* general features: + * On-demand (:kbd:`Tab`) and "dot" automatic code completion + * Automatic popup calltips showing function signatures + * Go-to-definition for any symbol: Functions, classes, attributes, etc. (:kbd:`Ctrl`-Click or :kbd:`Ctrl-G` by default) - * MATLAB-like PYTHONPATH management dialog box (works with all consoles) - * Windows only: current user environment variables editor - * direct links to documentation (Python, Matplotlib, !NumPy, !Scipy, etc.) - * direct link to Python(x,y) launcher - * direct links to !QtDesigner, !QtLinguist and !QtAssistant (Qt documentation) + * Occurrence highlighting: Select or double-click any word to show all other instances throughout the current document + * On-the-fly automatic formatters (optional): -* *preferences* dialog box: + * Automatic insertion of closing quotes parentheses, braces and brackets + * Automatic indentation after 'else', 'elif', 'finally', etc. + * Smart auto-indentation based on code structure + * Automatic insertion of colons after for, if, def, etc. + * Automatically fix mixed indentation, EOL characters and trailing spaces - * keyboard shortcuts - * syntax coloring schemes (source editor, history log, help) - * console: background color (black/white), automatic code completion, etc. - * and a lot more... + * Real-time code analysis: + * Errors/warnings/problems (powered by ``pyflakes``) + * PEP 8 and code style (powered by ``pycodestyle``) + * Code annotation parsing and "Todo lists" (``TODO``, ``FIXME``, ``XXX``, etc.) .. image:: images/mainwindow/mainwindow_dark_1610.png :align: right :width: 60% :alt: The Spyder main window, with a dark syntax highlighting theme applied +* :doc:`ipythonconsole`: -* :doc:`editor`: - - * syntax coloring (Python, C/C++, Fortran) - * *breakpoints* and *conditional breakpoints* (debugger: `pdb`) - * run or debug Python scripts (see console features) - * *run configuration* dialog box: - - * working directory - * command line options - * run in a new Python interpreter or in an existing Python interpreter or IPython client - * Python interpreter command line options + * Any number of individual consoles, each executed in a separate, isolated processes + * Each console uses the full IPython kernel as a backend with a light GUI frontend + * Supports all of the powerful IPython magic commands and functionality + * Automatic code completion and calltips, and automatic link to :doc:`help` + * Range of code run options and interactivity + * :doc:`debugging` integration with enhanced ``ipdb`` debugger and the :doc:`editor` + * Inline display of Matplotlib graphics (optional) + * The :guilabel:`User Module Reloader`, automatically re-importing modified source files - * *code outline explorer*: functions, classes, if/else/try/... statements - * *powerful code introspection features* (powered by `rope`): +* :doc:`variableexplorer`: - * *code completion* - * *calltips* - * *go-to-definition*: go to object (any symbol: function, class, attribute, etc.) definition by pressing Ctrl+Left mouse click on word or Ctrl+G (default shortcut) + * Can list all global variables, functions, classes, and other objects, or filter them by several criteria + * GUI-based editors for numerous data types (numeric, strings, collections, NumPy arrays, Pandas DataFrames, dates/times, images, and more) + * Import/export data or an entire session from/to many formats (text, csv, NumPy files, MATLAB files) + * Interactive data visualization options (plot, histogram, image...) using Matplotlib - * *occurrence highlighting* - * typing helpers (optional): +* :doc:`help`: - * automatically insert closing parentheses, braces and brackets - * automatically unindent after 'else', 'elif', 'finally', etc. + * Provides documentation or source code for any Python object (class, function, module...) + * Can be triggered manually, on demand (:kbd:`Ctrl-I` by default) or automatically on typing a left parenthesis after a function name (optional) + * Real-time rendering and rich HTML display of the popular ``numpydoc`` docstring format (powered by ``Sphinx``) - * *to-do* lists (TODO, FIXME, XXX) - * errors/warnings (real-time *code analysis* provided by `pyflakes`) - * integrated static code analysis (using `pylint`) - * direct link to `winpdb` external debugger +* :doc:`pylint`: Detects an array of style issues, bad practices, potential bugs, and other problems with your code (powered by ``pylint``) +* :guilabel:`Profiler`: Measures the performance impact of every function in a script to identify bottlenecks and aid optimization +* :doc:`projects`: Allows for easy saving and restoring of settings, sessions and setup for working on multiple development efforts simultaneously +* :doc:`fileexplorer`: Integrated filesystem viewing supporting many common operations +* :doc:`findinfiles`: Find string occurrences in a file, directory, or entire project with full support for powerful regular expressions and excluded locations +* :doc:`onlinehelp`: Search and browse rich HTML documentation on installed Python modules, packages, functions, classes, builtins and more, including your own +* :doc:`historylog`: Chronologically records every command entered into any Spyder console with timestamps, syntax highlighting and de-duplication +* :doc:`internalconsole`: Provides access to viewing, exploring and controlling Spyder's own operation .. image:: images/mainwindow/mainwindow_matlab_1610.png :align: right :width: 60% :alt: The Spyder main window, with a panel layout mirroring that of MATLAB +* Preferences: -* :doc:`ipythonconsole`: - - * *all consoles are executed in a separate process* - * *code completion*/calltips and automatic link to help (see below) - * open Python interpreters or basic terminal command windows - * run Python scripts (see source editor features) - * *variable explorer*: - - * *GUI-based editors* for a lot of data types (numbers, strings, lists, arrays, dictionaries, ...) - * *import/export data* from/to a lot of file types (text files, !NumPy files, MATLAB files) - * multiple array/list/dict editor instances at once, thus allowing to compare variable contents - * data visualization - -* :doc:`historylog` -* :doc:`help`: - - * provide documentation or source code on any Python object (class, function, module, ...) - * documentation may be displayed as an html page thanks to the rich text mode (powered by `sphinx`) + * Fully customizable keyboard shortcuts editor + * Selection of a custom Python interpreter to use for consoles + * Choice of 10 built-in syntax coloring theme, or create your own + * Toggle automatic editor and console introspection, analysis and helper features + * Options to use a variety of graphics backends and display preferences + * Much more... -* :doc:`onlinehelp`: automatically generated html documentation on installed Python modules -* :doc:`findinfiles`: find string occurrences in a directory, a git repository or directly in PYTHONPATH (support for regular expressions and included/excluded string lists) -* :doc:`fileexplorer` -* :doc:`projects` +* General Features: + * MATLAB-like ``PYTHONPATH`` management dialog + * User environment variables viewer/editor (Windows-only) + * Handy links to useful resources and documentation (Python, Matplotlib, NumPy, Scipy, Qt, IPython, etc.) + * Interactive tour, tutorial and shortcut cheat sheet for new users -Spyder may also be used as a PyQt5 or PyQt4 extension library -(module 'spyder'). For example, the Python interactive shell widget -used in Spyder may be embedded in your own PyQt5 or PyQt4 application. +Beyond its many built-in features, Spyder's abilities can be extended even further via its plugin system and API. +Spyder can also be used as a PyQt5 extension library, allowing you to build upon its functionality and embed its components, such as the interactive console, in your own software. diff --git a/doc/projects.rst b/doc/projects.rst index d73cba2a7..12b0a9641 100644 --- a/doc/projects.rst +++ b/doc/projects.rst @@ -1,60 +1,83 @@ +######## Projects -======== +######## -Spyder allows users to associate a given directory with a project. This has two -main advantages: +Spyder allows users to associate a given directory with a **Project**, which offers several main advantages: -1. Projects remember the list of open files in Editor. This permits to easily - work on several coding efforts at the same time. -2. The project's path is added to the list of paths Python looks modules for, so - that modules developed as part of a project can be easily imported in any - console. +* Opening, closing or switching to a :guilabel:`Project` automatically saves and restores your :doc:`editor` panes and open files to exactly how you left off. + This allows you to easily switch between many different development tasks without having to manually re-create your session for each one. +* Your project's root directory is automatically added to the ``PYTHONPATH``, so you can easily ``import`` and work with any modules and packages you create with zero setup. +* The project path is also used to automatically set your working directory, and can be used as an automatic preset for several modules, such as the :doc:`findinfiles` search location. +* You can browse all your :guilabel:`Project` files from the :ref:`Project Explorer `, regardless of your current working directory or :doc:`fileexplorer` location. +* :guilabel:`Projects` are :ref:`integrated ` with the ``git`` version control system, allowing you to commit files and open them or your repository in the ``gitk`` GUI right from within Spyder. -To create a project, it is necessary to select the *New Project* entry from the -*Projects* menu: +.. note:: -.. image:: images/menu/menu_projects.png - :align: center + :guilabel:`Projects` are completely optional and not imposed on users. + All of Spyder' functionality (session saving, File Explorer, working directory, etc) is available without creating a :guilabel:`Project`, just on a global rather than :guilabel:`Project`-specific basis. + + +================== +Creating a Project +================== + +To create a :guilabel:`Project`, click the :guilabel:`New Project` entry in the :guilabel:`Projects` menu, choose whether you'd like to associate a :guilabel:`Project` with an existing directory or make a new one, and enter the :guilabel:`Project` 's name and path: + +|projectsmenu| |newprojectdialog| + +.. |projectsmenu| + image:: images/menu/menu_projects.png + :width: 37% :alt: Closeup of Spyder's Projects menu, containing project-related commands +.. |newprojectdialog| + image:: images/dialog/dialog_new_project.png + :width: 62% + :alt: New project dialog, with options to set the name, type and location + | -When a project is activated, the *Project explorer* pane is shown, which -presents a tree view structure of the current project. Through this pane, -it is possible to make several operations on the files that belong to project: -|explorer| |contextmenu| +.. _project-explorer: -.. |explorer| image:: images/projects/project_explorer_standard.png - :width: 30% +========================== +Using the Project Explorer +========================== + +Once a :guilabel:`Project` is opened, the :guilabel:`Project Explorer` pane is shown, presenting a tree view of the current :guilabel:`Project` 's files and directories. +This pane allows you to perform all the same operations as a normal Spyder :doc:`fileexplorer`. + +|projectexplorer| |projectcontextmenu| + +.. |projectexplorer| + image:: images/projects/project_explorer_standard.png + :width: 40% :alt: Spyder Project Explorer, displaying a directory tree of project files -.. |contextmenu| image:: images/projects/project_explorer_inset_contextmenu.png +.. |projectcontextmenu| + image:: images/projects/project_explorer_inset_contextmenu.png :width: 50% :alt: Inset of the context-menu for a directory in project explorer | -.. note:: Projects are completely optional and not imposed on users, i.e. users - can work without creating any project. +.. _vcs-section: +============================ +Working with version control +============================ -Version Control Integration ---------------------------- +Spyder has basic integration with the `Git`_ distributed version control system. +You can commit or browse (in the ``gitk`` GUI) a file, directory or the entire repository via the commands in the context menu for the relevant object (right-click). -Spyder has limited integration with Git_ and Mercurial_. Commit and browse -commands are available by right-clicking on relevant files that reside within -an already initialized repository. This menu assume that certain commands are -available on the system path. +.. _Git: https://git-scm.com/ -* For Mercurial repositories, TortoiseHG_ must be installed, and either ``thg`` - or ``hgtk`` must be on the system path. -* For git repositories, the commands ``git`` and ``gitk`` must be on the - system path. For Windows systems, the `Git for Windows`_ package provides a - convenient installer and the option to place common git commands on the - system path without creating conflicts with Windows system tools. - The second option in the dialog below is generally a safe approach. +To use this functionality, the :guilabel:`Project` must be located in a ``git`` repository and the ``git`` and ``gitk`` commands must be on the system path. +For Windows systems, the `Git for Windows`_ package provides a convenient installer and the option to place common git commands on the system path without creating conflicts with Windows system tools. +The second option in the dialog below is generally a safe approach. + +.. _Git for Windows: https://gitforwindows.org/ .. image:: images/other/git_for_windows_install_path.png :align: center @@ -62,7 +85,9 @@ available on the system path. | -.. _Git: http://git-scm.com/ -.. _Mercurial: http://mercurial.selenic.com/ -.. _TortoiseHg: http://tortoisehg.bitbucket.org/ -.. _Git for Windows: https://git-for-windows.github.io/ + +Related components +~~~~~~~~~~~~~~~~~~ + +* :doc:`editor` +* :doc:`fileexplorer` diff --git a/doc/pylint.rst b/doc/pylint.rst index 5092fdc04..4bb31dfa0 100644 --- a/doc/pylint.rst +++ b/doc/pylint.rst @@ -1,16 +1,38 @@ -Static code analysis -==================== +#################### +Static Code Analysis +#################### -The static code analysis tool may be used directly from the :doc:`editor`, or -by entering manually the Python module or package path - i.e. it works either -with `.py` (or `.pyw`) Python scripts or with whole Python packages -(directories containing an `__init__.py` script). +The **Static Code Analysis** pane detects style issues, bad practices, potential bugs, and other quality problems in your code, all without having to actually execute it. +Spyder's static analyzer is powered by the best in class `Pylint`_ back-end, which can intelligently detect an enormous and customizable range of problem signatures. + +.. _Pylint: https://www.pylint.org/ .. image:: images/pylint/static_analysis_standard.png :alt: Spyder Pylint pane, showing numerous issues discovered in a file | -Related plugins: + +========================= +Using the static analyzer +========================= + +You can select the desired file to analyze directly in the :doc:`editor` by clicking anywhere within it, or you can manually enter the Python module or package path you'd like it to check in the path entry textbox in the :guilabel:`Static Code Analysis` pane. +The analyzer works with both ``.py`` (or ``.pyw``) Python scripts and whole Python packages (directories containing an :file:`__init__.py` file). +Then, to run it, select :menuselection:`Sour&ce --> Run static code analysis` from the menubar, click the :guilabel:`Analyze` button in the pane, or press the configurable static analysis shortcut (:kbd:`F8` by default). +Cancel analyzing a file with the :guilabel:`Stop` button, and if analysis fails, click the :guilabel:`Output` button to find out why. + +To go directly to the file and line in the :doc:`editor` highlighted by a failed check, just click its name. +You can click the dropdown or press the :kbd:`Down Arrow` key in the filename field to view results of previous analyses; the number of recent runs Spyder should remember can be customized in the :guilabel:`History` dialog from the :guilabel:`Static Code Analysis` context menu. +All standard checks are run by default. +You can turn certain messages off at the line, block or file/module level by adding a ``# pylint: disable=`` comment at the respective level, where the ``<...>`` portion should be replaced with a comma-separated list (or single value) without the ``<``/``>`` of Pylint message names (*e.g.* ``multiple-statements``, or ``fixme, line-too-long``; you can also use error codes like ``C0321`` although names are preferred for clarity). +Or, you can globally suppress certain messages by editing the :file:`.pylintrc` configuration file in your user home directory. +For more details on configuring Pylint, see the `Pylint documentation`_. + +.. _Pylint documentation: https://pylint.readthedocs.io/en/latest/faq.html#message-control + + +Related components +~~~~~~~~~~~~~~~~~~ * :doc:`editor` diff --git a/doc/variableexplorer.rst b/doc/variableexplorer.rst index 68493c2a8..635af9c14 100644 --- a/doc/variableexplorer.rst +++ b/doc/variableexplorer.rst @@ -1,8 +1,8 @@ +################# Variable Explorer -================= +################# -The variable explorer shows the namespace contents (i.e. all global object -references) of the current console +The **Variable Explorer** shows the namespace contents (all global object references, such as variables, functions, modules, etc.) of the currently selected :doc:`ipythonconsole` session, and allows you to interact with them through a variety of GUI-based editors. .. image:: images/variable_explorer/variable_explorer_standard.png :align: center @@ -10,9 +10,13 @@ references) of the current console | -The following screenshots show some interesting features such as editing -lists, strings, dictionaries, NumPy arrays, or plotting/showing NumPy arrays -data. + +==================== +Features and editors +==================== + +Spyder's :guilabel:`Variable Explorer` offers built in support for editing lists, strings, dictionaries, NumPy arrays, Pandas DataFrames, and more, and can also histogram, plot, or even display some of them as an RGB image. +Several examples of this functionality follow: | @@ -40,13 +44,15 @@ data. | -|contextmenu| |histogram| +|varexpcontextmenu| |histogram| -.. |contextmenu| image:: images/variable_explorer/variable_explorer_inset_contextmenu_array.png +.. |varexpcontextmenu| + image:: images/variable_explorer/variable_explorer_inset_contextmenu_array.png :width: 45% - :alt: Variable Explorer with a contextmenu, including plot/histogram options + :alt: Variable Explorer with a context menu, including plot/histogram options -.. |histogram| image:: images/variable_explorer/variable_explorer_histogram.png +.. |histogram| + image:: images/variable_explorer/variable_explorer_histogram.png :width: 50% :alt: Plot window showing a histogram, generated via the previous options @@ -54,7 +60,7 @@ data. .. image:: images/variable_explorer/variable_explorer_contextmenu_array.png :align: center - :alt: Contextmenu for an int array, with the Show image option selected + :alt: Context menu for an int array, with the Show image option selected .. image:: images/plot_window/plot_window_show_image.png :align: center @@ -63,25 +69,30 @@ data. | +=============== Supported types ---------------- - -The variable explorer can't show all types of objects. The ones currently -supported are: - -#. `Pandas` DataFrame, TimeSeries and Index objects -#. `NumPy` arrays and matrices -#. `PIL/Pillow` images -#. `datetime` dates -#. Integers -#. Floats -#. Complex numbers -#. Lists -#. Sets -#. Dictionaries -#. Tuples -#. Strings - -Related plugins: - +=============== + +The Variable Explorer has specialized editors for a range of common built-in and third-party Python objects, and can view, edit, and deeply introspect most arbitrary objects via a more general :guilabel:`Object explorer`. +Types with specialized editing support include: + +* Integers +* Floats +* Complex numbers +* Strings +* ``datetime`` dates and ``Timedelta`` s +* Lists +* Tuples +* Sets +* Dictionaries +* NumPy arrays and matrices +* Pandas ``DataFrame``, ``TimeSeries`` and ``Index`` (any type) objects +* ``PIL``/``Pillow`` images +* Namespaces + + +Related components +~~~~~~~~~~~~~~~~~~ + +* :doc:`debugging` * :doc:`ipythonconsole`