Describe and clarify caveats with the Editor's "Run file" executing in an empty namespace

[CAM-Gerlach]

Issue Report

Issue Description

Adapted from my comment originally made in a Google Doc with @steff456 and @hyounes4560 that resulted in #331

This one's a little tricky for us to explain, but also rather important to explain well to users, e.g. as an important admonition.

Specifically, it refers to the default behavior (i.e. if Run in console's namespace instead of an empty one is checked in either the global or per-file Run configuration) where when running a file with Run File, the code is executed in a fresh, empty namespace rather than the console's one, so if e.g. in a new console, they run

[In 1] a = 3

Then they have a script that's just e.g.

print(a * 2)

Running the script with Run File will cause it to exit with a NameError, as the script does not define the name a (which is usually a user error).

However, the console's namespace (and thus the Variable Explorer, etc) will update with any updated values from the script, e.g. if they have a script

a = 6
b = a * 2

After running it, the value of the name a in the console will be set to 6, and the name b will be defined as having the value 12.

This behavior helps avoid common user mistakes and hard to debug script behavior, but can confuse some users as to why scripts aren't "seeing" the names or their values they define in the Console (and users have raised issues about it), so its worth explaining clearly, IMO.

Where is the relevant portion of the documentation located?

In Panes --> Editor --> Running code --> Run File

What would you suggest it be replaced with?

A description of the above

Other information

• Is the problem specific to documentation for a particular version of Spyder?

  • N/A
  • Spyder 5 (master)
  • Spyder 4 (4.x)
  • Spyder 3 (3.x, frozen)

• Are you planning on submitting a Github pull request with a suitable change?

  • Yes
  • No
  • Maybe so