From 01421bec1e0d25df17599cfa1160adbbcd08e949 Mon Sep 17 00:00:00 2001 From: Cheryl Sabella Date: Thu, 20 Dec 2018 00:38:54 -0500 Subject: bpo-35521: IDLE: Add code context section to docs (#11205) Also add some internal cross-references. --- Doc/library/idle.rst | 41 ++++++++++++++++++---- Lib/idlelib/help.html | 39 ++++++++++++++------ .../IDLE/2018-12-20-00-14-15.bpo-35521.x32BRn.rst | 2 ++ 3 files changed, 65 insertions(+), 17 deletions(-) create mode 100644 Misc/NEWS.d/next/IDLE/2018-12-20-00-14-15.bpo-35521.x32BRn.rst diff --git a/Doc/library/idle.rst b/Doc/library/idle.rst index 384d2bf..449e54f 100644 --- a/Doc/library/idle.rst +++ b/Doc/library/idle.rst @@ -146,7 +146,7 @@ Go to Line Show Completions Open a scrollable list allowing selection of keywords and attributes. See - Completions in the Tips sections below. + :ref:`Completions ` in the Editing and navigation section below. Expand Word Expand a prefix you have typed to match a full word in the same window; @@ -154,7 +154,8 @@ Expand Word Show call tip After an unclosed parenthesis for a function, open a small window with - function parameter hints. + function parameter hints. See :ref:`Calltips ` in the + Editing and navigation section below. Show surrounding parens Highlight the surrounding parenthesis. @@ -278,8 +279,8 @@ Configure IDLE Code Context (toggle)(Editor Window only) Open a pane at the top of the edit window which shows the block context - of the code which has scrolled above the top of the window. Clicking a - line in this pane exposes that line at the top of the editor. + of the code which has scrolled above the top of the window. See + :ref:`Code Context ` in the Editing and Navigation section below. Window menu (Shell and Editor) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -310,8 +311,8 @@ Turtle Demo Run the turtledemo module with example Python code and turtle drawings. Additional help sources may be added here with the Configure IDLE dialog under -the General tab. See the "Help sources" subsection below for more -on Help menu choices. +the General tab. See the :ref:`Help sources ` subsection below +for more on Help menu choices. .. index:: single: Cut @@ -359,6 +360,8 @@ Squeeze the code above and the prompt below down to a 'Squeezed text' label. +.. _editing-and-navigation: + Editing and navigation ---------------------- @@ -431,6 +434,9 @@ are restricted to four spaces due to Tcl/Tk limitations. See also the indent/dedent region commands in the edit menu. + +.. _completions: + Completions ^^^^^^^^^^^ @@ -475,6 +481,8 @@ much can be found by default, e.g. the re module. If you don't like the ACW popping up unbidden, simply make the delay longer or disable the extension. +.. _calltips: + Calltips ^^^^^^^^ @@ -503,6 +511,25 @@ In an editor, import statements have no effect until one runs the file. One might want to run a file after writing the import statements at the top, or immediately run an existing file before editing. +.. _code-context: + +Code Context +^^^^^^^^^^^^ + +Within an editor window containing Python code, code context can be toggled +in order to show or hide a pane at the top of the window. When shown, this +pane freezes the opening lines for block code, such as those beginning with +``class``, ``def``, or ``if`` keywords, that would have otherwise scrolled +out of view. The size of the pane will be expanded and contracted as needed +to show the all current levels of context, up to the maximum number of +lines defined in the Configure IDLE dialog (which defaults to 15). If there +are no current context lines and the feature is toggled on, a single blank +line will display. Clicking on a line in the context pane will move that +line to the top of the editor. + +The text and background colors for the context pane can be configured under +the Highlights tab in the Configure IDLE dialog. + Python Shell window ^^^^^^^^^^^^^^^^^^^ @@ -768,6 +795,8 @@ with the default subprocess if at all possible. Help and preferences -------------------- +.. _help-sources: + Help sources ^^^^^^^^^^^^ diff --git a/Lib/idlelib/help.html b/Lib/idlelib/help.html index e2bf773..b5f12d1 100644 --- a/Lib/idlelib/help.html +++ b/Lib/idlelib/help.html @@ -202,13 +202,14 @@ be undone.
Move cursor to the line number requested and make that line visible.
Show Completions
Open a scrollable list allowing selection of keywords and attributes. See -Completions in the Tips sections below.
+Completions in the Editing and navigation section below.
Expand Word
Expand a prefix you have typed to match a full word in the same window; repeat to get a different expansion.
Show call tip
After an unclosed parenthesis for a function, open a small window with -function parameter hints.
+function parameter hints. See Calltips in the +Editing and navigation section below.
Show surrounding parens
Highlight the surrounding parenthesis.
@@ -314,8 +315,8 @@ by editing or deleting one or more of the files in .idlerc.

Code Context (toggle)(Editor Window only)
Open a pane at the top of the edit window which shows the block context -of the code which has scrolled above the top of the window. Clicking a -line in this pane exposes that line at the top of the editor.
+of the code which has scrolled above the top of the window. See +Code Context in the Editing and Navigation section below.
@@ -344,8 +345,8 @@ and open docs.python.org showing the latest Python documentation.
Run the turtledemo module with example Python code and turtle drawings.

Additional help sources may be added here with the Configure IDLE dialog under -the General tab. See the “Help sources” subsection below for more -on Help menu choices.

+the General tab. See the Help sources subsection below +for more on Help menu choices.

Context Menus

@@ -383,7 +384,7 @@ the code above and the prompt below down to a ‘Squeezed text’ label.
-

Editing and navigation

+

Editing and navigation

Editor windows

IDLE may open editor windows when it starts, depending on settings @@ -445,7 +446,7 @@ are restricted to four spaces due to Tcl/Tk limitations.

See also the indent/dedent region commands in the edit menu.

-

Completions

+

Completions

Completions are supplied for functions, classes, and attributes of classes, both built-in and user-defined. Completions are also provided for filenames.

@@ -480,7 +481,7 @@ much can be found by default, e.g. the re module.

longer or disable the extension.

-

Calltips

+

Calltips

A calltip is shown when one types ( after the name of an accessible function. A name expression may include dots and subscripts. A calltip remains until it is clicked, the cursor is moved out of the argument area, @@ -502,6 +503,21 @@ not import turtle. The menu or shortcut do nothing either. Enter might want to run a file after writing the import statements at the top, or immediately run an existing file before editing.

+
+

Code Context

+

Within an editor window containing Python code, code context can be toggled +in order to show or hide a pane at the top of the window. When shown, this +pane freezes the opening lines for block code, such as those beginning with +class, def, or if keywords, that would have otherwise scrolled +out of view. The size of the pane will be expanded and contracted as needed +to show the all current levels of context, up to the maximum number of +lines defined in the Configure IDLE dialog (which defaults to 15). If there +are no current context lines and the feature is toggled on, a single blank +line will display. Clicking on a line in the context pane will move that +line to the top of the editor.

+

The text and background colors for the context pane can be configured under +the Highlights tab in the Configure IDLE dialog.

+

Python Shell window

With IDLE’s Shell, one enters, edits, and recalls complete statements. @@ -733,7 +749,7 @@ with the default subprocess if at all possible.

Help and preferences

-

Help sources

+

Help sources

Help menu entry “IDLE Help” displays a formatted html version of the IDLE chapter of the Library Reference. The result, in a read-only tkinter text window, is close to what one sees in a web browser. @@ -801,6 +817,7 @@ also used for testing.

  • Automatic indentation
  • Completions
  • Calltips
    • +
  • Code Context
  • Python Shell window
  • Text colors
    • @@ -899,7 +916,7 @@ also used for testing.



    - Last updated on Nov 12, 2018. + Last updated on Dec 19, 2018. Found a bug?
    diff --git a/Misc/NEWS.d/next/IDLE/2018-12-20-00-14-15.bpo-35521.x32BRn.rst b/Misc/NEWS.d/next/IDLE/2018-12-20-00-14-15.bpo-35521.x32BRn.rst new file mode 100644 index 0000000..120de7f --- /dev/null +++ b/Misc/NEWS.d/next/IDLE/2018-12-20-00-14-15.bpo-35521.x32BRn.rst @@ -0,0 +1,2 @@ +Document the IDLE editor code context feature. Add some internal references +within the IDLE doc. -- cgit v0.12