From 276e3056ca2df0c8d9bbb50a13a7c5d5e93a3641 Mon Sep 17 00:00:00 2001 From: "Dan Taylor (VS)" Date: Fri, 19 Jan 2018 15:00:44 -0800 Subject: [PATCH 1/4] Improved getting started instructions on readme and contributing guide --- CONTRIBUTING.md | 2 +- README.md | 62 +++++++++++++++++++++++++++---------------------- 2 files changed, 35 insertions(+), 29 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6aede91fc0fc..aa0be15a0691 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,7 +4,7 @@ ### Prerequisites -1. Node.js (>= 8.9.1, < 9.0.0) +1. Node.js (>= 8.9.1, < 9.0.0), and [Yarn](https://yarnpkg.com/lang/en/docs/install/) 2. Python 2.7 or later (required only for testing the extension and running unit tests) 3. Windows, OS X or Linux 4. Visual Studio Code diff --git a/README.md b/README.md index cd17a9f93100..3211ed9f8793 100644 --- a/README.md +++ b/README.md @@ -1,28 +1,43 @@ # Python extension for Visual Studio Code -A [Visual Studio Code](https://code.visualstudio.com/) [extension](https://marketplace.visualstudio.com/VSCode) with rich support for the [Python language](https://www.python.org/) (_including Python 3.6_), with features including the following and more: -* Linting ([Prospector](https://pypi.io/project/prospector/), [Pylint](https://pypi.io/project/pylint/), [pycodestyle](https://pypi.io/project/pycodestyle/), [Flake8](https://pypi.io/project/flake8/), [pylama](https://github.com/klen/pylama), [pydocstyle](https://pypi.io/project/pydocstyle/), [mypy](http://mypy-lang.org/) with config files and plugins) -* Intellisense (autocompletion with support for PEP 484 and PEP 526) -* Auto indenting -* Code formatting ([autopep8](https://pypi.io/project/autopep8/), [yapf](https://pypi.io/project/yapf/), with config files) -* Code refactoring (Rename, Extract Variable, Extract Method, Sort Imports) -* Viewing references, code navigation, view signature -* Excellent debugging support (remote debugging over SSH, mutliple threads, django, flask) -* Running and debugging Unit tests ([unittest](https://docs.python.org/3/library/unittest.html#module-unittest), [pytest](https://pypi.io/project/pytest/), [nose](https://pypi.io/project/nose/), with config files) -* Execute file or code in a python terminal -* Snippets +A [Visual Studio Code](https://code.visualstudio.com/) [extension](https://marketplace.visualstudio.com/VSCode) with rich support for the [Python language](https://www.python.org/) (_including Python 3.6_), with features such as linting, debugging, IntelliSense, code navigation, code formatting, refactoring, unit tests, snippets, and more! ## Quick Start -* Install the extension -* optionally install `ctags` for Workspace Symbols, from [here](http://ctags.sourceforge.net/), or using `brew install ctags` on macOS -* Select your Python interpreter - + If it's already in your path then you're set - + Otherwise, to select a different Python interpreter/version/environment (use the command `Select Workspace Interpreter` or look in the status bar) +* **Step 1.** [Install a supported version of Python on your system](https://code.visualstudio.com/docs/python/python-tutorial#_prerequisites) (note: that the system install of Python on macOS is not supported) +* **Step 2.** Install the extension +* **Step 3.** Open or create a Python file and start coding! + +### Optional +* **Step 4.** [Install a linter](https://code.visualstudio.com/docs/python/linting) to get errors and warnings -- you can further customize linting rules to fit your needs +* **Step 5.** Select your preferred Python interpreter + + By default we use the one that's on your path + + To select a different Python interpreter/version/environment (use the command `Select Interpreter`, or if you have a workspace open you can click in the status bar) +* **Step 6.** Install `ctags` for Workspace Symbols, from [here](http://ctags.sourceforge.net/), or using `brew install ctags` on macOS + +You can [follow our Python tutorial](https://code.visualstudio.com/docs/python/python-tutorial#_prerequisites) for step-by-step instructions for building a simple app, and check out the [Python documentation on the VS Code site](https://code.visualstudio.com/docs/languages/python) for more information. + +## Useful Commands + +Open the Command Palette (Command+Shift+P on macOS and Ctrl+Shift+P on Windows/Linux) and type in one of the following commands: + +Command | Description +--- | --- +```Python: Select Interpreter``` | Switch between Python interpreters, versions, and environments. +```Python: Start REPL``` | Start an interactive Python REPL using the selected interpreter in the VS Code terminal. +```Python: Run Python File in Terminal``` | Runs the active Python file in the VS Code terminal. You can also run a Python file by right-clicking on the file and selecting ```Run Python File in Terminal```. +```Python: Select Linter``` | Switch from PyLint to flake8 or other supported linters. -## [Documentation](https://code.visualstudio.com/docs/languages/python) +## Supported locales + +The extension is available in multiple languages thanks to external +contributors (if you would like to contribute a translation, see the +[pull request which added simplified Chinese](https://github.com/Microsoft/vscode-python/pull/240)): -For further information and details continue through to the [documentation](https://code.visualstudio.com/docs/languages/python). +* `en` +* `ja` +* `ru` +* `zh-cn` ## Questions, Issues, Feature Requests, and Contributions @@ -41,7 +56,7 @@ For further information and details continue through to the [documentation](http + Code definition (Peek and hover definition, View signatures) + Rename refactoring + Sorting import statements (use the `Python: Sort Imports` command) -* Intellisense and Autocomplete (including PEP 484 support) +* Intellisense and Autocomplete (including PEP 484 and PEP 526 support) + Ability to include custom module paths (e.g. include paths for libraries like Google App Engine, etc.; use the setting `python.autoComplete.extraPaths = []`) * Code formatting + Auto formatting of code upon saving changes (default to 'Off') @@ -82,16 +97,7 @@ For further information and details continue through to the [documentation](http ![Unit Tests](https://raw.githubusercontent.com/microsoft/vscode-python/master/images/unittest.gif) -## Supported locales - -The extension is available in multiple languages thanks to external -contributors (if you would like to contribute a translation, see the -[pull request which added simplified Chinese](https://github.com/Microsoft/vscode-python/pull/240)): -* `en` -* `ja` -* `ru` -* `zh-cn` ## Data/Telemetry From 8d9c878857f32296e2f1235b30ab7da81544d0b5 Mon Sep 17 00:00:00 2001 From: "Dan Taylor (VS)" Date: Fri, 19 Jan 2018 15:56:20 -0800 Subject: [PATCH 2/4] Wording changes to README.md --- README.md | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 3211ed9f8793..ce20769d98d6 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,23 @@ # Python extension for Visual Studio Code -A [Visual Studio Code](https://code.visualstudio.com/) [extension](https://marketplace.visualstudio.com/VSCode) with rich support for the [Python language](https://www.python.org/) (_including Python 3.6_), with features such as linting, debugging, IntelliSense, code navigation, code formatting, refactoring, unit tests, snippets, and more! +A [Visual Studio Code](https://code.visualstudio.com/) [extension](https://marketplace.visualstudio.com/VSCode) with rich support for the [Python language](https://www.python.org/) (_including Python 3.6_), including features such as linting, debugging, IntelliSense, code navigation, code formatting, refactoring, unit tests, snippets, and more! ## Quick Start -* **Step 1.** [Install a supported version of Python on your system](https://code.visualstudio.com/docs/python/python-tutorial#_prerequisites) (note: that the system install of Python on macOS is not supported) -* **Step 2.** Install the extension +* **Step 1.** [Install a supported version of Python on your system](https://code.visualstudio.com/docs/python/python-tutorial#_prerequisites) (note: that the system install of Python on macOS is not supported). +* **Step 2.** Install the Python extension for Visual Studio Code. * **Step 3.** Open or create a Python file and start coding! -### Optional -* **Step 4.** [Install a linter](https://code.visualstudio.com/docs/python/linting) to get errors and warnings -- you can further customize linting rules to fit your needs -* **Step 5.** Select your preferred Python interpreter - + By default we use the one that's on your path - + To select a different Python interpreter/version/environment (use the command `Select Interpreter`, or if you have a workspace open you can click in the status bar) -* **Step 6.** Install `ctags` for Workspace Symbols, from [here](http://ctags.sourceforge.net/), or using `brew install ctags` on macOS +### Optional Steps +* **Step 4.** [Install a linter](https://code.visualstudio.com/docs/python/linting) to get errors and warnings -- you can further customize linting rules to fit your needs. +* **Step 5.** Select your preferred Python interpreter/version/environment using the `Select Interpreter` command. + + By default we use the one that's on your path. + + If you have a workspace open you can also click in the status bar to change the interpreter. +* **Step 6.** Install `ctags` for Workspace Symbols, from [here](http://ctags.sourceforge.net/), or using `brew install ctags` on macOS. -You can [follow our Python tutorial](https://code.visualstudio.com/docs/python/python-tutorial#_prerequisites) for step-by-step instructions for building a simple app, and check out the [Python documentation on the VS Code site](https://code.visualstudio.com/docs/languages/python) for more information. +For more information you can: +* [Follow our Python tutorial](https://code.visualstudio.com/docs/python/python-tutorial#_prerequisites) with step-by-step instructions for building a simple app. +* Check out the [Python documentation on the VS Code site](https://code.visualstudio.com/docs/languages/python) for general information about using the extension. ## Useful Commands From a907e84f2f635abc23dc8867dc8da6c2006975e3 Mon Sep 17 00:00:00 2001 From: "Dan Taylor (VS)" Date: Fri, 19 Jan 2018 16:05:47 -0800 Subject: [PATCH 3/4] Mention vscode warning in contributor guide --- CONTRIBUTING.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index aa0be15a0691..04abf6a0df58 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -20,6 +20,8 @@ cd vscode-python yarn install ``` +You may see warnings that ```The engine "vscode" appears to be invalid.```, you can ignore these. + ### Incremental Build Run the `Compile` and `Hygiene` build Tasks from the [Command Palette](https://code.visualstudio.com/docs/editor/tasks) (short cut `CTRL+SHIFT+B` or `โ‡งโŒ˜B`) From 86ace61b2cfebf24a74acc9cdf0c5e2859f5edbf Mon Sep 17 00:00:00 2001 From: "Dan Taylor (VS)" Date: Tue, 23 Jan 2018 12:30:52 -0800 Subject: [PATCH 4/4] Incorporated Chet's feedback: sentence casing, header size, see all commands --- README.md | 38 ++++++++++++++++++++------------------ 1 file changed, 20 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index ce20769d98d6..c8d3639b7b7b 100644 --- a/README.md +++ b/README.md @@ -2,13 +2,13 @@ A [Visual Studio Code](https://code.visualstudio.com/) [extension](https://marketplace.visualstudio.com/VSCode) with rich support for the [Python language](https://www.python.org/) (_including Python 3.6_), including features such as linting, debugging, IntelliSense, code navigation, code formatting, refactoring, unit tests, snippets, and more! -## Quick Start +## Quick start * **Step 1.** [Install a supported version of Python on your system](https://code.visualstudio.com/docs/python/python-tutorial#_prerequisites) (note: that the system install of Python on macOS is not supported). * **Step 2.** Install the Python extension for Visual Studio Code. * **Step 3.** Open or create a Python file and start coding! -### Optional Steps +## Optional steps * **Step 4.** [Install a linter](https://code.visualstudio.com/docs/python/linting) to get errors and warnings -- you can further customize linting rules to fit your needs. * **Step 5.** Select your preferred Python interpreter/version/environment using the `Select Interpreter` command. + By default we use the one that's on your path. @@ -19,17 +19,19 @@ For more information you can: * [Follow our Python tutorial](https://code.visualstudio.com/docs/python/python-tutorial#_prerequisites) with step-by-step instructions for building a simple app. * Check out the [Python documentation on the VS Code site](https://code.visualstudio.com/docs/languages/python) for general information about using the extension. -## Useful Commands +## Useful commands Open the Command Palette (Command+Shift+P on macOS and Ctrl+Shift+P on Windows/Linux) and type in one of the following commands: -Command | Description ---- | --- +Command | Description +--- | --- ```Python: Select Interpreter``` | Switch between Python interpreters, versions, and environments. ```Python: Start REPL``` | Start an interactive Python REPL using the selected interpreter in the VS Code terminal. ```Python: Run Python File in Terminal``` | Runs the active Python file in the VS Code terminal. You can also run a Python file by right-clicking on the file and selecting ```Run Python File in Terminal```. ```Python: Select Linter``` | Switch from PyLint to flake8 or other supported linters. +To see all available Python commands, open the Command Palette and type ```Python```. + ## Supported locales The extension is available in multiple languages thanks to external @@ -41,7 +43,7 @@ contributors (if you would like to contribute a translation, see the * `ru` * `zh-cn` -## Questions, Issues, Feature Requests, and Contributions +## Questions, issues, feature requests, and contributions * If you have a question about how to accomplish something with the extension, please [ask on Stack Overflow](https://stackoverflow.com/questions/tagged/visual-studio-code+python) * If you come across a problem with the extension, please [file an issue](https://github.com/microsoft/vscode-python) @@ -50,15 +52,15 @@ contributors (if you would like to contribute a translation, see the - If someone has already [file an issue](https://github.com/Microsoft/vscode-python) that encompasses your feedback, please leave a ๐Ÿ‘/๐Ÿ‘Ž reaction on the issue - Otherwise please file a new issue -## Feature Details +## Feature details -* IDE-like Features +* IDE-like features + Automatic indenting + Code navigation ("Go to", "Find all" references) + Code definition (Peek and hover definition, View signatures) + Rename refactoring + Sorting import statements (use the `Python: Sort Imports` command) -* Intellisense and Autocomplete (including PEP 484 and PEP 526 support) +* Intellisense and autocomplete (including PEP 484 and PEP 526 support) + Ability to include custom module paths (e.g. include paths for libraries like Google App Engine, etc.; use the setting `python.autoComplete.extraPaths = []`) * Code formatting + Auto formatting of code upon saving changes (default to 'Off') @@ -67,19 +69,19 @@ contributors (if you would like to contribute a translation, see the + Support for multiple linters with custom settings (default is [Pylint](https://pypi.io/project/pylint/), but [Prospector](https://pypi.io/project/prospector/), [pycodestyle](https://pypi.io/project/pycodestyle/), [Flake8](https://pypi.io/project/flake8/), [pylama](https://github.com/klen/pylama), [pydocstyle](https://pypi.io/project/pydocstyle/), and [mypy](http://mypy-lang.org/) are also supported) * Debugging + Watch window - + Evaluate Expressions + + Evaluate expressions + Step through code ("Step in", "Step out", "Continue") - + Add/remove break points + + Add/remove breakpoints + Local variables and arguments + Multi-threaded applications + Web applications (such as [Flask](http://flask.pocoo.org/) & [Django](https://www.djangoproject.com/), with template debugging) + Expanding values (viewing children, properties, etc) - + Conditional break points + + Conditional breakpoints + Remote debugging (over SSH) + Google App Engine + Debugging in the integrated or external terminal window + Debugging as sudo -* Unit Testing +* Unit testing + Support for [unittest](https://docs.python.org/3/library/unittest.html#module-unittest), [pytest](https://pypi.io/project/pytest/), and [nose](https://pypi.io/project/nose/) + Ability to run all failed tests, individual tests + Debugging unit tests @@ -87,10 +89,10 @@ contributors (if you would like to contribute a translation, see the * Miscellaneous + Running a file or selected text in python terminal * Refactoring - + Rename Refactorings - + Extract Variable Refactorings - + Extract Method Refactorings - + Sort Imports + + Rename refactorings + + Extract variable refactorings + + Extract method refactorings + + Sort imports ![General Features](https://raw.githubusercontent.com/microsoft/vscode-python/master/images/general.gif) @@ -101,7 +103,7 @@ contributors (if you would like to contribute a translation, see the -## Data/Telemetry +## Data and telemetry The Microsoft Python Extension for Visual Studio Code collects usage data and sends it to Microsoft to help improve our products and