Merge pull request #1350 from brettcannon/py-doc-touchups

Changes for various issues related to Python

Author: Kraig Brockschmidt

docs/languages/python.md

@@ -11,7 +11,9 @@ MetaDescription: Learn about Visual Studio Code features (code completion, debug
 
 Working with Python in Visual Studio Code, using the [Microsoft Python extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python), is simple, fun, and productive. The extension leverages all of VS Code's power to provide auto complete and IntelliSense, linting, debugging, and unit testing, along with control over your Python environments.
 
-Note that the Python extension depends on a separate installation of Python itself. For details, see [Tutorial - Prerequisites](/docs/python/python-tutorial.md#prerequisites).
+## Install Python and the Python Extension
+
+The [tutorial](/docs/python/python-tutorial.md) guides you through installing Python and using the extension.
 
 ## Autocomplete and IntelliSense
 

docs/python/debugging.md

@@ -137,7 +137,7 @@ To debug an app that requires administrator privileges, use `"console": "externa
 
 Remote debugging allows you to step through a program locally within VS Code while it's executed on a remote computer. In this case, it's necessary to have the source code on both computers.
 
-1. On both development and remote computers, install the [ptvsd library](https://pypi.org/project/ptvsd/) (version `3.0.0` - later versions are not yet supported [#514](https://github.com/Microsoft/vscode-python/issues/514)).
+1. On both development and remote computers, install [ptvsd 3.0.0](https://pypi.org/project/ptvsd/3.0.0/) (version `3.0.0` **exactly** - later versions are not yet supported [#514](https://github.com/Microsoft/vscode-python/issues/514)).
 2. In the source code on both computers, add the following lines, replacing *my_secret* with the appropriate passphrase to authenticate remote debugging, and replacing *address* with the appropriate IP address (or `localhost`) and port number:
 
     ```python
@@ -240,7 +240,7 @@ There are many reasons why the debugger may not work; oftentimes the debug conso
 
 | Cause | Solution |
 | --- | --- |
-| The path to the python executable is incorrect | Check the value in the `pythonPath` setting of `launch.json`, restarting VS Code if you make a change. |
+| The path to the python executable is incorrect | Check the value in the `pythonPath` setting of `settings.json`. |
 | Invalid expressions in watch window (see detailed output below) | Clear all expressions from the Watch window restart the debugger. |
 
 Detailed output for invalid expressions:

docs/python/editing.md

@@ -76,7 +76,6 @@ The Python extension supports source code formatting using either autopep8 (the
 
 | Setting<br/>(python.formatting.) | Default value | Description |
 | --- | --- | --- |
-| outputWindow | `"Python"` | The name of the output window for formatting messages. |
 | provider | `"autopep8"` | Specifies the formatter to use, either "autopep8" or "yapf". |
 
 ### Formatter-specific settings
@@ -101,7 +100,7 @@ If formatting fails, check the following possible causes:
 
 | Cause | Solution |
 | --- | --- |
-| The path to the python interpreter is incorrect | Check the `pythonPath` setting. Restart VS Code if you make a correction. |
+| The path to the python interpreter is incorrect | Check the `pythonPath` setting. |
 | The formatter is not installed in the current environment | Open a command prompt, navigate to the location specified in the `pythonPath` setting, and run `pip install` for the formatter.
 | The path to the formatter is incorrect. | Check the value of the appropriate `python.formatting.<formatter>Path` setting. |
 | Custom arguments for the formatter are incorrect. | Check that the appropriate `python.formatting.<formatter>Path` setting does not contain arguments, and that `python.formatting.<formatter>Args` contains an array of individual argument items such as `"python.formatting.yapfArgs": ["--style", "{based_on_style: chromium, indent_width: 20}"]`.

docs/python/environments.md

@@ -39,15 +39,14 @@ If the interpreter you want to use is not located automatically, you can set the
 
 For example:
 
-    Windows:
-    ```json
-    "python.pythonPath": "c:/python36/python.exe"
-    ```
-
-    Mac/Linux:
-    ```json
-    "python.pythonPath": "/home/python36/python"
-    ```
+- Windows:
+  ```json
+  "python.pythonPath": "c:/python36/python.exe"
+  ```
+- Mac/Linux:
+  ```json
+  "python.pythonPath": "/home/python36/python"
+  ```
 
 ## Environment variables in the interpreter path
 
@@ -81,7 +80,6 @@ To use a Python interpreter that's installed in a virtual environment:
 
 2. Configure the same `python.pythonPath` variable in `launch.json`.
 3. Ensure that the the libraries and modules you plan on using for linting are installed within the virtual environment.
-4. Restart VS Code.
 
 ## Python interpreter for debugging
 

docs/python/python-tutorial.md

@@ -16,14 +16,14 @@ Let's get started by creating the simplest "Hello World" Python application.
 
 To successfully complete this tutorial, you must do the following:
 
-1. Install the [Python extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python)
+1. Install the [Python extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python).
 
 2. Install whichever version of Python you want to use. Options include:
 
   - The built-in Python installation on Linux.
-  - An installation through Homebrew on Linux or macOS.
-  - A download from [python.org](https://www.python.org/)
-  - A download from [Anaconda](https://www.anaconda.com/download/).
+  - An installation through [Homebrew](https://brew.sh/) on macOS using `brew install python3` (the system install of Python on macOS is not supported).
+  - A download from [python.org](https://www.python.org/downloads/).
+  - A download from [Anaconda](https://www.anaconda.com/download/) (for data science purposes).
 
 3. From within VS Code, select a version of Python using the **Python: Select Interpreter** command on the **Command Palette** (`kb(workbench.action.showCommands)`), or by using the **Select Python Environment** option on the Status Bar if available:
 

docs/python/settings-reference.md

@@ -50,7 +50,6 @@ Workspace symbols are symbols in C source code generated by the ctags tool (desc
 
 | Setting<br/>(python.formatting.) | Default | Description | See also |
 | --- | --- | --- | --- |
-| outputWindow | `"Python"` | The name of the output window for formatting messages. |[Editing - Formatting](/docs/python/editing.md#formatting) |
 | provider | `"autopep8"` | Specifies the formatter to use, either "autopep8" or "yapf". |[Editing - Formatting](/docs/python/editing.md#formatting) |
 | autopep8Path | `"autopep8"` | Path to autopep8 | [Editing - Formatting](/docs/python/editing.md#formatting) |
 | autopep8Args| `[]` | Arguments for autopep8, each argument as a separate item in the array. | [Editing - Formatting](/docs/python/editing.md#formatting) |