classification
Title: Cross-reference isolated mode from relevant locations
Type: enhancement Stage: patch review
Components: Documentation Versions: Python 3.8, Python 3.7, Python 3.6
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, ncoghlan, xtreak
Priority: normal Keywords: easy, patch

Created on 2018-03-18 05:57 by ncoghlan, last changed 2018-06-17 13:42 by xtreak.

Files
File name Uploaded Description Edit
33095.patch xtreak, 2018-06-17 05:44
Pull Requests
URL Status Linked Edit
PR 7764 open xtreak, 2018-06-17 13:42
Messages (3)
msg314022 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2018-03-18 05:57
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
msg319804 - (view) Author: Karthikeyan Singaravelan (xtreak) * (Python triager) Date: 2018-06-17 05:44
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
msg319812 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2018-06-17 11:40
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.
History
Date User Action Args
2018-06-17 13:42:56xtreaksetstage: needs patch -> patch review
pull_requests: + pull_request7372
2018-06-17 11:40:55ncoghlansetmessages: + msg319812
2018-06-17 05:44:46xtreaksetfiles: + 33095.patch

nosy: + xtreak
messages: + msg319804

keywords: + patch
2018-03-18 10:40:23jwilksetnosy: - jwilk
2018-03-18 05:57:16ncoghlancreate