<type>documentation</type>
<domain>edit</domain>
<id>source-assistant</id>
<title>Source Assistant</title>
<date>$Date$</date>
<version>$Revision$</version>
<product>per+</product>

The `Source Assistant <script:show-panel-source-assistant>`__ tool in Wing Personal and
Wing Pro displays detailed information about source symbols in the editor, auto-completer,
and tools such as the ``Project``, ``Search in Files``, ``Python Shell``, ``Debug Console``,
and ``Source Browser``.

The display includes links to the point of definition of the selected symbol, the symbol's
probable type or types, and a link to each type's point of definition. Depending on
context and symbol type, the ``Source Assistant`` will also display docstrings, call
signature, return type, super-classes, overridden methods, and links into Python standard
library documentation.

When invoking a function, method, or other callable object, the ``Source Assistant``
highlights the current argument in the call signature and displays information both for
the invoked callable and the current argument or auto-completer selection.

The information displayed in the ``Source Assistant`` is based on a combination of static
and runtime `source code analysis <ref:edit/source-code-analysis>`__.  In some code,
where static analysis is not successful, running the debugger to a breakpoint allows
Wing access to complete and correct code analysis.  See `Helping Wing Analyze Code
<ref:edit/helping-wing-analyze-code>`__ for more hints on helping Wing understand your 
source code.

Docstring Type and Validity
---------------------------

The ``Source Assistant`` can inspect and display documentation found in docstrings in
various ways, either (1) focusing on displaying as much information as possible, even if the
docstring cannot be parsed as structured text, or (2) focusing instead on providing parse
error information so that docstring formatting can be improved. The display is configured
with the **Source Assistant Options** described below.

By default the ``Source Assistant`` displays a type and validity indicator, showing
whether the docstring was successfully parsed or reformatted, and focuses on displaying
as much information as cleanly as possible, even if docstrings have formatting problems.

The following indicator messages may appear with each docstring:

**✔ PEP287** indicates the docstring parsed successfully using PEP 287 `reStructuredText
Docstring Format <http://legacy.python.org/dev/peps/pep-0287/>`__ and is being rendered
accordingly.

**✖ PEP287** indicates that the docstring does not parse successfully as
reStructuredText and is showing inline parse errors.

**Rewrapped** indicates that the docstring is being shown as plain text but Wing has
heuristically rewrapped paragraphs.

**Plain Text** indicates the docstring is being shown as plain text, exactly as it appears
in the source code. PEP 287 style docstrings may fall back to plain text if they cannot be
parsed.

Source Assistant Options
------------------------

There are several options available to select how Wing renders docstrings, and whether
or not the display should focus on flagging docstring parse errors. These are accessed by
right clicking on the ``Source Assistant``:

**Use PEP 287 docstrings** causes Wing to attempt to render docstrings by treating them as
PEP 287 `reStructuredText Docstring Format
<http://legacy.python.org/dev/peps/pep-0287/>`__. When disabled, docstrings are always
shown as plain text instead.

**Show PEP 287 parse errors** is disabled by default to focus on showing as much information as
possible and not on diagnosing docstring formatting errors. Wing will try to display
docstrings as rendered reStructuredText even if they contain parse errors. Wing uses a set
of heuristics to gloss over common errors so the docstring can be rendered, or in more
severe cases, falls back to showing the docstring as plain text. When this option is
enabled, Wing will shift its focus to reporting PEP 287 parse errors that equal or exceed
the ``PEP 287 parse error threshold`` in severity. Errors are shown in the context of its
reStructuredText rendering of the docstring.

**PEP 287 parse error threshold** sets the error level at or above which Wing will
determine that parsing the PEP 287 docstring has failed. When below this level, a best
effort will be made to render the docstring without showing any errors. When above this
level, Wing either shows the parse errors in the rendered docstring, if ``Show PEP 287
parse errors`` is enabled and the docstring can be parsed, or falls back to showing
the docstring in plain text. The default is to treat warnings, errors, and severe errors
as parse errors.

**Rewrap plain text docstrings** causes Wing to employ a heuristic to rewrap paragraphs in
docstrings not being rendered as reStructuredText, in order to make better use of space.
This option can be disabled to show the docstring exactly as it appears in the source
code.

**Show docstring type and validity** enables or disables the docstring type and
validity indicator in the top right of the docstring area.

**Always show docstrings** causes Wing to show all docstrings for all symbols in the
``Source Assistant``, even if it is displaying information both for an invocation and
current argument type. This is disabled by default, to save space by showing only the
docstring for the last symbol.

The ``Source Assistant`` right-click context menu can also be used to copy text or HTML to
the clipboard, change the display font size, and access this documentation.

Goto Definition from Documentation
----------------------------------

PEP 287 docstrings may include references that link to the point of definition of a named
symbol in Python code. This is done using an interpreted text role in the following form::

  :py:`symbol`
  
The symbol may be a simple name like ``MyClass`` or a dotted name like
``modulename.MyClass`` or ``modulename.MyClass.SomeMethod``.

When docstrings containing symbol references are rendered in the ``Source Assistant``,
they will generate a link to the symbol's point of definition. Clicking the link will
resolve the point of definition by looking first for the symbol in the same scope as the
class, method, or function that the docstring describes, and if that is unsuccessful then
by attempting to look up the name on the project's effective Python Path.

To return from the point of definition, use the back arrow in the top left of the 
editor area.

For example, specifying ``:py:`path``` looks for ``path`` in the scope of the
described symbol and then looks for a module named ``path`` on the Python Path. If
``:py:`sys.path.abspath``` is used instead then the process looks for
``sys.path.abspath`` in the scope of the described symbol, then looks for a module named
``sys`` with an attribute ``path.abspath``, and finally looks for a module named
``sys.path`` with an attribute ``abspath``. This works even if the referenced module is
not imported in the scope of the described object.

In addition to the ``:py:`` role, Wing follows `Sphinx
<https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html>`__ to support
the ``py:mod``, ``py:func``, ``py:data``, ``py:const``, ``py:class``, ``py:meth``,
``py:attr``, ``py:exc``, and ``py:obj`` interpreted text roles. However, there is no
difference in how the point of definition is found for each of these.

Python Standard Library Documentation Links
-------------------------------------------

For symbols in the Python standard library, Wing will attempt to compute a documentation
URL whenever possible. Since there is no formal mapping from standard library code to
documentation, these URLs are generated heuristically. They are often, but not always
correct.

Standard library documentation URLs point to https://docs.python.org/ but can be
redirected to another server with the `Source Analysis > Advanced > Python Docs URL Prefix
<script:show_preferences_gui(prefname="pysource.python-doc-url-prefix")>`__ preference. To
access locally stored documentation, a local http server must be used because ``#``
bookmark references do not work with ``file:`` URLs.

