Updating docs with installation and usage instructions (#50)

[PBI:30144]

* Adding installation and how to use instructions

* Updating the get started for devs docs with pywin32 and link to how to use the extension docs

* Minor docs improvements

* Addressing PR comments

* Addressing PR comments for wording

README.md

@@ -27,5 +27,7 @@ contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additio
 
 ## Documentation
 
+- [Installation instructions](/docs/install.md)
+- [How to use the Extension](/docs/how-to-use.md)
 - [Setup for developers](/docs/developers-setup.md)
 - [Contributing](CONTRIBUTING.md)

docs/developers-setup.md

@@ -6,11 +6,11 @@
 
   - Download link : https://nodejs.org/en/download/
 
-- Python 3 (or latest)
+- Python 3.7.4 (or latest)
 
   - Download link : https://www.python.org/downloads/
-  - /!\ Make sure Python is in your path (during installation or insert it manually afterwards)
-  - /!\ Make sure pip is added to your environment variables as well
+  - **NOTE :** Make sure Python is in your path under an environment variable named `python` (during installation or insert it manually afterwards)
+  - **NOTE :** Make sure pip is added to your environment variables as well
     (for example it could be find at : c:\users\<alias>\appdata\local\programs\python\python37\lib\site-packages\pip)
   - Run in a console `python -m pip install --upgrade pip`
 
@@ -21,6 +21,10 @@
       (Link to download : https://visualstudio.microsoft.com/vs/older-downloads under
       'Redistributables and Build tools' : 'Microsoft Build Tools 2015')
 
+- Pywin32
+
+  - Run the command in a console : `pip install pywin32`
+
 - VS Code
 
 - Python extension for VS Code (download from VS Code market place)
@@ -41,10 +45,11 @@
 
 ## Notes on how to use it
 
+- [Documentation to use the Extension](/docs/how-to-use.md)
 - Debugging the extension opens a new VS Code window with the extension installed
 - From the original VS Code window (opened in our repository) you can see outputs in the Debug Console
 - In the new VS Code window, you can access the commands provided by the extension from the Commands Palette (Ctrl+Shift+P)
-  listed as 'Adafruit : ...'
+  listed as 'Pacifica : ...'
 - If you change some files you'll need to run the 'npm run compile' command again and restart debugging
 
 ## Repository Structure (important files)

docs/how-to-use.md

@@ -0,0 +1,57 @@
+# How to use the Extension
+
+Commands are accessible through :
+
+- **The command palette** (`Ctrl+shift+P` or `View->Command Palette`) and type 'Pacifica : `command_name`'
+- **The extension buttons** available on the top right of the Text Editor Panel when you have a Python file open
+
+## Available commands
+
+- **Open Simulator** : opens the webview of the simulator.
+
+- **New Project** : opens an unsaved file with links to help you and a code snippet that you can save as `code.py` / `main.py`.  
+  _(**Note :** will open the simulator webview if it's not open yet)_.
+
+- **Run Simulator** : run the code you have open on the simulator (make sure you've clicked on a valid code file).  
+  _(**Note :** will open the simulator webview if it's not open yet)_.
+
+- **Deploy to Device** : saves the code to a Circuit Playground Express.  
+  _(**Note :** the board needs to be correctly formatted to a `CIRCUITPY` drive first if it's not the case : [Installing CircuitPython](https://learn.adafruit.com/welcome-to-circuitpython/installing-circuitpython))_.
+
+## Available features
+
+- We currently support the [Adafruit Circuit Playground Express board](https://www.adafruit.com/product/3333)
+- Access to auto-completion and Python error flagging
+- Output panel for the simulator (without print statements)
+- Deploy to the physical device (if correctly formatted)
+- Device's features :
+  - NeoPixels
+  - Buttons (A & B)
+  - Sound - .wav files
+  - Red LED
+  - Switch
+
+## Not supported yet
+
+- User print statements
+- Updating the simulator's state without needing to call the`show` method
+- Auto-detect/format the device
+- Serial monitor for the device
+- Debugger for the simulator
+- Device's features
+  - Light sensor
+  - Temperature sensor
+  - Motion sensors
+  - Sound sensor
+  - Touch sensors
+  - Sound - tones
+  - Green LED
+  - IR transmitter
+
+## Troubleshooting Tips
+
+- The first time you install the extension, you'll need to execute the `run` command at least once in order to access auto-completion.
+- While running a code file, if you get an error saying it can't find the file, make sure you've clicked on a valid Python code file before running it.
+- To open the output panel again after closing it go to VS Code menu : `View->Output`.
+- If you have pylint enabled, it might underline the import of the adafruit_circuitplayground library, but it will work correctly.
+- If you try to deploy to the device while it's plugged in but you still get an error saying it cannot find the board, make sure your Circuit Playground Express is formatted correctly and that its name matches `CIRCUITPY`.

docs/install.md

@@ -0,0 +1,28 @@
+# Instructions on How to Install and Run the Extension
+
+## Steps to manually install the extension
+
+1. Link to the latest releases :
+   [Releases](https://github.com/microsoft/vscode-python-embedded/releases)
+2. Click on the latest release
+3. At the bottom of the page download the .vsix file
+4. To install the .vsix file :
+   - Go to the directory where the downloaded vsix file is and run in a command console: `code --install-extension <vsix file name>`
+   - Or in VS Code, go to the extension tab (a), in menu (b) select 'Install from VSIX' (c) and search the file you downloaded
+     ![VSIX Install Instructions](./vsix-install-instructions.png)
+
+## Prerequisites
+
+- [VS Code](https://code.visualstudio.com/Download)
+- [Node](https://nodejs.org/en/download/)
+- [Python 3.7.4 (or latest)](https://www.python.org/downloads/)
+- Python VS Code extension (download from VS Code Marketplace)
+- Simple audio :
+  - `python -m pip install --upgrade pip`
+  - `pip install simpleaudio`
+  - **Troubleshoot :** If it's not working make sure you have pip and C++ 2015 build tools installed ([Download link](https://visualstudio.microsoft.com/vs/older-downloads), and look under 'Redistributables and Build tools' : 'Microsoft Build Tools 2015')
+- Pywin32 : `pip install pywin32`
+
+## How to use the extension
+
+- [How to use the Extension](/docs/how-to-use.md)