Merge from 3.x: PR spyder-ide#44

Fixes spyder-ide#13
Fixes spyder-ide#15
Fixes spyder-ide#16
Fixes spyder-ide#43
Fixes spyder-ide#46

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`

doc/editor.rst

@@ -1,63 +1,69 @@
+######
 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
    :alt: Spyder's Editor panel, split horizontally and with style analysis
 
 |
 
-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
    :alt: Spyder's Editor panel, showing an example of a code cell
 
 |
 
-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)
-* `# <codecell>` (IPython notebook cell separator)
+* ``#%%`` (standard cell separator)
+* ``# %%`` (standard cell separator, when file has been edited with Eclipse)
+* ``# <codecell>`` (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`

doc/fileexplorer.rst

@@ -1,26 +1,31 @@
+#############
 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
    :alt: File Explorer context menu, with common file manipulation tasks
 
 |
 
-Related plugins:
 
-* :doc:`ipythonconsole`
+Related components
+~~~~~~~~~~~~~~~~~~
+
 * :doc:`editor`
+* :doc:`findinfiles`
+* :doc:`projects`

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`

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`

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`