Wing Python IDE

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 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. 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 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 preference. To access locally stored documentation, a local http server must be used because # bookmark references do not work with file: URLs.