From 8b8c3277e7c7c981f08ee0aa8a4d5c22ec4aff6b Mon Sep 17 00:00:00 2001 From: Hanan Younes <56159764+hyounes4560@users.noreply.github.com> Date: Sun, 2 Oct 2022 12:31:04 -0400 Subject: [PATCH] Add documentation for the Outline pane (#327) * Add documentation and images for the outline pane * Use literal formatting for special comments in Outline pane * Tweak crop and compress Options menu image for Outline pane * Clean up line breaks & spaces in Outline pane * Apply/fix reST formatting and capitalize Outline/outline consistently * Use consistent tense in options menu item list in Outline pane * Add reviewer feedback Co-authored-by: C.A.M. Gerlach Co-authored-by: Stephannie Jimenez Gacha --- doc/images/outline/outline-options-menu.png | Bin 0 -> 12193 bytes .../outline-standard.png} | Bin doc/panes/outline.rst | 58 ++++++++++++++++++ 3 files changed, 58 insertions(+) create mode 100644 doc/images/outline/outline-options-menu.png rename doc/images/{editor/editor-outline-standard.png => outline/outline-standard.png} (100%) create mode 100644 doc/panes/outline.rst diff --git a/doc/images/outline/outline-options-menu.png b/doc/images/outline/outline-options-menu.png new file mode 100644 index 0000000000000000000000000000000000000000..f8d43210d361624ae774600a8c3deae3f5ccfb6b GIT binary patch literal 12193 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 Panes --> Outline` or :kbd:`Ctrl-Shift-O` / :kbd:`Cmd-Shift-O`. +Click an entry in the outline to jump to its source file location, and use the :guilabel:`Go to cursor position` toolbar button to highlight the item corresponding to the current :doc:`editor` position. + +.. image:: /images/outline/outline-standard.png + :alt: Outline pane + + + +============ +Options menu +============ + +The options menu in the top-right of the pane allows customizing how the outline is displayed. + +.. image:: /images/outline/outline-options-menu.png + :alt: Outline options menu + +These customization settings include: + +* :guilabel:`Show absolute path`: Display the full path to each file instead of just the name. +* :guilabel:`Show all files`: List every open file rather than just the current one. + This allows using the Outline as a file switcher. +* :guilabel:`Group code cells`: Group code cells in multiple nested levels in the outline rather than showing all cells in one level. + You can create subsections by adding more ``%`` signs to the cell separator. +* :guilabel:`Display variables and attributes`: Display top-level variable/constant definitions and class attributes in the outline. +* :guilabel:`Follow cursor position`: Automatically highlight and expand the entry corresponding to the current cursor position in the :doc:`editor`. +* :guilabel:`Show special comments`: List special comments in the outline, which start with ``# ----``. +* :guilabel:`Sort files alphabetically`: Sort the file list in alphabetical order. + When disabled, all tabs will be sorted by the tab order of the currently selected Editor panel. + + + +===== +Icons +===== + +The following icons are used for outline elements: + +* :guilabel:`m` for methods +* :guilabel:`f` for functions +* :guilabel:`c` for classes +* :guilabel:`%` for code cells +* :guilabel:`#` for comments + + + +============= +Related panes +============= + +* :doc:`editor` +* :doc:`fileexplorer` +* :doc:`projects`