Cross-reference isolated mode from relevant locations

[ncoghlan]

BPO	33095
Nosy	@ncoghlan, @JulienPalard, @miss-islington, @tirkarthi
PRs	bpo-33095: Add reference to isolated mode in -m and script option #7764 [3.8] bpo-33095: Add reference to isolated mode in -m and script option (GH-7764) #16180 [3.7] bpo-33095: Add reference to isolated mode in -m and script option (GH-7764) #16181
Files	33095.patch

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2020-01-04.14:45:35.073>
created_at = <Date 2018-03-18.05:57:16.223>
labels = ['easy', '3.8', 'type-feature', '3.7', 'docs']
title = 'Cross-reference isolated mode from relevant locations'
updated_at = <Date 2020-01-04.14:45:35.071>
user = 'https://github.com/ncoghlan'

bugs.python.org fields:

activity = <Date 2020-01-04.14:45:35.071>
actor = 'xtreak'
assignee = 'docs@python'
closed = True
closed_date = <Date 2020-01-04.14:45:35.073>
closer = 'xtreak'
components = ['Documentation']
creation = <Date 2018-03-18.05:57:16.223>
creator = 'ncoghlan'
dependencies = []
files = ['47644']
hgrepos = []
issue_num = 33095
keywords = ['patch', 'easy']
message_count = 7.0
messages = ['314022', '319804', '319812', '352399', '352540', '352542', '359291']
nosy_count = 5.0
nosy_names = ['ncoghlan', 'docs@python', 'mdk', 'miss-islington', 'xtreak']
pr_nums = ['7764', '16180', '16181']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue33095'
versions = ['Python 3.6', 'Python 3.7', 'Python 3.8']

[ncoghlan]

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

[tirkarthi]

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

[ncoghlan]

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.

[ncoghlan]

New changeset bdd6945 by Nick Coghlan (Xtreak) in branch 'master':
bpo-33095: Add reference to isolated mode in -m and script option (GH-7764)
bdd6945

[miss-islington]

New changeset 07186c3 by Miss Islington (bot) in branch '3.8':
bpo-33095: Add reference to isolated mode in -m and script option (GH-7764)
07186c3

[JulienPalard]

New changeset 210dc3b 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)
210dc3b

[tirkarthi]

Closing since PRs were merged. Thanks for the review.