In https://bugs.python.org/issue33053#msg313966, jwilk noted that it isn't obvious from https://docs.python.org/3/using/cmdline.html#cmdoption-m how to keep the current directory from being added to `sys.path` when using the -m switch. The answer is to pass the `-I` switch as well (to activate isolated mode), but there's no cross reference to help readers discover that fact.

https://docs.python.org/3/using/cmdline.html#id2 is the main documentation for isolated mode, so the steps needed to close this issue are:

1. At least add a reference from the -m switch documentation to the -I switch documentation
2. Review the other parts of the `using` docs that describe how `sys.path` is initialised, and reference the -I switch documentation where relevant

There are four parts where I could see sys.path manipulation being mentioned while running scripts : 

-c option (https://docs.python.org/3/using/cmdline.html#cmdoption-c)
-m option (https://docs.python.org/3/using/cmdline.html#cmdoption-m)
-  (input option) 
<script> (running as script)

For some reason I am not able to hyperlink to - and <script> parts since they are not a command line option but a method to execute code. I could sys.path references in windows (https://docs.python.org/3/using/windows.html#finding-modules) where `._pth` file is mentioned to completely override sys.path. 

I am new to adding documentation so add in if it needs a simple reference or explain the option which I feel redundant and useful at the same time kind of missing the point of cross-referencing. I am attaching a patch for `-m` and <script> option. Feel free to add comments and if I am missing something.

Thanks

xtreak: if you're familiar with GitHub workflows, then we now accept docs and code updates as GitHub PRs: https://devguide.python.org/pullrequest/

The parts about running the tests aren't exactly relevant here, what's more relevant is building the documentation: https://devguide.python.org/documenting/#building-the-documentation

In relation to your draft patch, I think that's a good starting point, but for -c and -m, it's the current directory that gets omitted, rather than "the script's directory" (that isn't well defined when anything other than a path is passed in).

For making "-" and "<script>" hyperlinkable, you'll need to add a label definition to the Sphinx source code immediately before those description sections. I'd suggest ".. _cmdarg-dash:" and ".. _cmdarg-script:" so the resulting anchors look similar to the option ones, without being the same.

New changeset bdd6945d4dbd1fe6a7fcff95f7d6908db7d791a1 by Nick Coghlan (Xtreak) in branch 'master':
bpo-33095: Add reference to isolated mode in -m and script option (GH-7764)
https://github.com/python/cpython/commit/bdd6945d4dbd1fe6a7fcff95f7d6908db7d791a1

New changeset 07186c3959a61c3d73b5ccae431cdd32afe70e5e by Miss Islington (bot) in branch '3.8':
bpo-33095: Add reference to isolated mode in -m and script option (GH-7764)
https://github.com/python/cpython/commit/07186c3959a61c3d73b5ccae431cdd32afe70e5e

New changeset 210dc3bb37ec57a8b8b16ffe0881181138a6e973 by Julien Palard in branch '3.7':
[3.7] bpo-33095: Add reference to isolated mode in -m and script option (GH-7764) (GH-16181)
https://github.com/python/cpython/commit/210dc3bb37ec57a8b8b16ffe0881181138a6e973

Closing since PRs were merged. Thanks for the review.

stage: patch review -> resolved

nosy: + xtreak
messages: + msg319804

keywords: + patch