├── .devcontainer ├── Dockerfile ├── devcontainer.json └── noop.txt ├── .github └── workflows │ ├── deploy-book.yml │ └── test-book.yml ├── .gitignore ├── .vscode └── extensions.json ├── 1-basics.md ├── 2-devtips.md ├── 3-remote.md ├── 4-collaboration.md ├── CODE_OF_CONDUCT.md ├── LICENCE ├── README.md ├── _config.yml ├── _toc.yml ├── architecture.md ├── challenges.md ├── data └── bees.csv ├── demo.ipynb ├── docs └── about.tex ├── environment.yml ├── history.md ├── pyproject.toml ├── src └── tutorial │ └── __init__.py ├── static ├── architecture │ ├── architecture-wsl.png │ ├── architecture.png │ └── extensions.png ├── history │ ├── gamma.jpg │ ├── json-rpc.png │ ├── monaco.png │ └── ship-schedule.png ├── image.png ├── logo-light.png ├── logo.png ├── references.bib ├── setting-json-tip.png ├── vscode-bit.png └── vscode-bit.svg └── yearbook2023.md /.devcontainer/Dockerfile: -------------------------------------------------------------------------------- 1 | FROM mcr.microsoft.com/devcontainers/miniconda:0-3 2 | 3 | # Copy environment.yml (if found) to a temp location so we update the environment. Also 4 | # copy "noop.txt" so the COPY instruction does not fail if no environment.yml exists. 5 | RUN conda install -n base -c conda-forge mamba 6 | COPY environment.yml* .devcontainer/noop.txt /tmp/conda-tmp/ 7 | RUN if [ -f "/tmp/conda-tmp/environment.yml" ]; then umask 0002 && /opt/conda/bin/mamba env create -f /tmp/conda-tmp/environment.yml; fi \ 8 | && rm -rf /tmp/conda-tmp 9 | 10 | -------------------------------------------------------------------------------- /.devcontainer/devcontainer.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "SciPy Demo", 3 | "build": { 4 | "context": "..", 5 | "dockerfile": "Dockerfile" 6 | }, 7 | 8 | // Features to add to the dev container. More info: https://containers.dev/features. 9 | // "features": {}, 10 | 11 | // Use 'forwardPorts' to make a list of ports inside the container available locally. 12 | // "forwardPorts": [] 13 | 14 | // Use 'postCreateCommand' to run commands after the container is created. 15 | "postCreateCommand": "conda init", 16 | 17 | // Configure tool-specific properties. 18 | "customizations": { 19 | "vscode": { 20 | "settings": { 21 | "python.defaultInterpreterPath": "/opt/conda/envs/tutorial" 22 | }, 23 | "extensions": [ 24 | "ms-python.python", 25 | "ms-toolsai.jupyter", 26 | "GitHub.codespaces", 27 | "ms-vscode-remote.remote-containers", 28 | "codezombiech.gitignore", 29 | "DavidAnson.vscode-markdownlint", 30 | "njpwerner.autodocstring", 31 | "ms-vscode-remote.vscode-remote-extensionpack", 32 | "GitHub.vscode-pull-request-github", 33 | "MS-vsliveshare.vsliveshare", 34 | "ms-vscode.live-server", 35 | "streetsidesoftware.code-spell-checker" 36 | ] 37 | } 38 | }, 39 | 40 | // Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root. 41 | "remoteUser": "vscode" 42 | } 43 | -------------------------------------------------------------------------------- /.devcontainer/noop.txt: -------------------------------------------------------------------------------- 1 | This file is copied into the container along with environment.yml* from the 2 | parent folder. This is done to prevent the Dockerfile COPY instruction from 3 | failing if no environment.yml is found. -------------------------------------------------------------------------------- /.github/workflows/deploy-book.yml: -------------------------------------------------------------------------------- 1 | name: deploy-book 2 | 3 | # Only run this when the master branch changes 4 | on: 5 | push: 6 | branches: 7 | - main 8 | 9 | # This job installs dependencies, build the book, and pushes it to `gh-pages` 10 | jobs: 11 | deploy-book: 12 | runs-on: ubuntu-latest 13 | defaults: 14 | run: 15 | shell: bash -l {0} 16 | steps: 17 | - uses: actions/checkout@v2 18 | 19 | # Install dependencies 20 | - name: Set up Python 3.11 21 | uses: actions/setup-python@v1 22 | with: 23 | python-version: 3.11 24 | 25 | - name: Install dependencies 26 | uses: conda-incubator/setup-miniconda@v2 27 | with: 28 | activate-environment: tutorial 29 | environment-file: environment.yml 30 | # Build the book 31 | - name: Build the book 32 | run: | 33 | conda activate tutorial 34 | jupyter-book build . 35 | # Push the book's HTML to github-pages 36 | - name: GitHub Pages action 37 | uses: peaceiris/actions-gh-pages@v3 38 | with: 39 | github_token: ${{ secrets.GITHUB_TOKEN }} 40 | publish_dir: ./_build/html -------------------------------------------------------------------------------- /.github/workflows/test-book.yml: -------------------------------------------------------------------------------- 1 | name: test-book 2 | 3 | # Only run this when the master branch changes 4 | on: 5 | pull_request: 6 | branches: 7 | - main 8 | workflow_dispatch: 9 | 10 | # This job installs dependencies and makes sure the book builds. 11 | jobs: 12 | deploy-book: 13 | runs-on: ubuntu-latest 14 | defaults: 15 | run: 16 | shell: bash -l {0} 17 | steps: 18 | - uses: actions/checkout@v2 19 | 20 | # Install dependencies 21 | - name: Set up Python 3.11 22 | uses: actions/setup-python@v1 23 | with: 24 | python-version: 3.11 25 | 26 | - name: Install dependencies 27 | uses: conda-incubator/setup-miniconda@v2 28 | with: 29 | activate-environment: tutorial 30 | environment-file: environment.yml 31 | # Build the book 32 | - name: Build the book 33 | run: | 34 | conda activate tutorial 35 | jupyter-book build . -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | _build 2 | Thumbs.db 3 | .DS_Store 4 | **.ipynb_checkpoints 5 | *.pyc 6 | -------------------------------------------------------------------------------- /.vscode/extensions.json: -------------------------------------------------------------------------------- 1 | { 2 | "recommendations": [ 3 | "ms-python.python", 4 | "donjayamanne.python-extension-pack", 5 | "ms-toolsai.jupyter", 6 | "GitHub.codespaces", 7 | "ms-azuretools.vscode-docker", 8 | "DavidAnson.vscode-markdownlint", 9 | "codezombiech.gitignore", 10 | "njpwerner.autodocstring", 11 | "ms-vscode-remote.vscode-remote-extensionpack", 12 | "ms-vscode.remote-repositories", 13 | "GitHub.vscode-pull-request-github", 14 | "MS-vsliveshare.vsliveshare", 15 | "ms-vscode.live-server", 16 | "streetsidesoftware.code-spell-checker" 17 | ] 18 | } 19 | -------------------------------------------------------------------------------- /1-basics.md: -------------------------------------------------------------------------------- 1 | # The basics of Python development in VS Code 2 | 3 | ## Some facts & figures 4 | 5 | - [Stack Overflow Annual Developer Surveys](https://insights.stackoverflow.com/survey): VS Code is the most popular integrated development environment (IDE) since 2018. 6 | 7 | | Year | VS Code* | Rank | 8 | |------|----------|------| 9 | | 2015 | Release | - | 10 | | 2016 | 7% | 13 | 11 | | 2017 | 23% | 5 | 12 | | 2018 | 35% | 1 | 13 | | 2019 | 51% | 1 | 14 | | 2020 | - | - | 15 | | 2021 | 71% | 1 | 16 | | 2022 | 74% | 1 | 17 | | 2023 | 74% | 1 | 18 | 19 | *Percentage of respondents using VS Code as a developer environment (multiple answers possible). 20 | 21 | - [2022 State of the Octoverse](https://octoverse.github.com/2022/state-of-open-source): [github.com/microsoft/vscode](https://github.com/microsoft/vscode) is `#1` repository on GitHub by number of contributors 22 | - The [VS Code Marketplace](https://marketplace.visualstudio.com/search?target=VSCode&category=All%20categories&sortBy=Installs) has 49k extensions as of July 2023 23 | 24 | What brought _us_ to VS Code? 25 | 26 | ## Getting started 27 | 28 | A brief overview of VS Code. 29 | 30 | - Launching VS Code 31 | - Local (Desktop icon / `code .`) 32 | - Browser: Primary option for workshop (https://vscode.dev/, `.` on any GitHub page) 33 | 34 | ```{admonition} Prep Exercise 35 | Follow the setup instructions in the [README](README.md#setup-instructions). For quick set-up we recommend using Codespaces directly from GitHub! 36 | ``` 37 | 38 | ## An anatomy of the VS Code UI 39 | 40 | How to navigate VS Code’s user interface. 41 | 42 | - Command Palette / Command center 43 | - Activity bar 44 | - Open folder 45 | - Search 46 | - Help: `?` 47 | - Status bar 48 | - Panel 49 | - [Accessibility](https://code.visualstudio.com/docs/editor/accessibility) (color themes, screen readers, screencast mode, etc.) 50 | - [VS Code terminal](https://code.visualstudio.com/docs/terminal/advanced) (xtermjs) 51 | - [Navigating without a mouse](https://www.youtube.com/watch?v=dJWJ0hCAkAI) 52 | 53 | ```{admonition} Exercise: Explore VS Code accessibility 54 | 1. Browse to the tutorial repo on GitHub and try opening it either in your browser (press `.` when on repo page) or cloning it locally and opening with `code .`. 55 | 2. Use the Command Palette to Zoom in and Zoom out (editor and/or view). 56 | 3. Search for Color Themes using the Extensions tab. You can find extensions or color themes that are accessible for color vision deficiencies, for example, take a look at the color blind-friendly extensions. If you are using a [screen reader](https://code.visualstudio.com/docs/editor/accessibility#_screen-readers) such as NVDA, JAWS and VoiceOver, try using it with VS Code! 57 | 4. Use the Command Palette or "gear" icon to change your Color Theme to a non-default one. 58 | ``` 59 | 60 | ## Customize your UI 61 | 62 | More fun and helpful UI features and settings. 63 | 64 | - Some key settings to check: 65 | - [Customizing Telemetry](https://code.visualstudio.com/docs/getstarted/telemetry) 66 | - Color themes: Dark, Colorblind 67 | - [Auto save](https://code.visualstudio.com/docs/editor/codebasics#_save-auto-save) 68 | - [Files default language](https://code.visualstudio.com/docs/languages/overview) 69 | - [Settings sync](https://code.visualstudio.com/docs/editor/settings-sync) 70 | - [Profiles](https://code.visualstudio.com/docs/editor/profiles) 71 | - [Python Dev profile template](https://code.visualstudio.com/docs/editor/profiles#_python-profile-template) 72 | - [Data Science profile template](https://code.visualstudio.com/docs/editor/profiles#_data-science-profile-template) 73 | - [Sarah's profile collection](https://dev.to/crazy4pi314/profiles-for-fun-and-profit-how-to-use-profiles-to-customize-vs-code-57hj) 74 | - [Extensions marketplace](https://code.visualstudio.com/docs/editor/extension-marketplace) 75 | - Don't see what you need? [Make your own!](https://code.visualstudio.com/api/get-started/your-first-extension) 76 | 77 | ```{admonition} Exercise: Share your profile 78 | 1. Create a new profile or use one of the templates. 79 | 2. Either in your local or browser-based VS Code, try customizing some settings, themes, font sizes, etc. 80 | 3. Export your current profile as a gist (or locally if you prefer). 81 | 4. Copy-paste the URL for your profile gist, and add it to the [discussion page](https://github.com/crazy4pi314/scipy-vscode-tutorial/discussions/17). 82 | 5. Try making a profile for presenting/screencasting or maybe a distraction-free writing space and take turns sharing all your cool new profiles with your team 😄 83 | 6. Try importing a profile created by someone else via the `Profiles` > `Import Profile...` option in the Gear menu! You can find @crazy4pi314's profiles [here](https://gist.github.com/crazy4pi314/a3b1157dcd0873d471fb79cf5dffaba4). 84 | ``` 85 | 86 | ## Setting up for Python development 87 | 88 | We will set up a Python project and install the necessary extensions. This piece is fairy quick and self-guided. 89 | 90 | - [Python Environments in VS Code](https://code.visualstudio.com/docs/python/environments#_creating-environments) 91 | - Default intrepreter settings 92 | - [Python environment manager](https://marketplace.visualstudio.com/items?itemName=donjayamanne.python-environment-manager) 93 | - Common Python extensions 94 | - [Python extension pack by Don Jayamanne](https://marketplace.visualstudio.com/items?itemName=donjayamanne.python-extension-pack) 95 | - [Jupyter](https://marketplace.visualstudio.com/items?itemName=ms-toolsai.jupyter) 96 | - formatters / linters: pylint, flake8, black, autopep8, ... 97 | 98 | ````{admonition} Exercise: New Python project from scratch 99 | 100 | 1. In the Codespace for this workshop or locally (in a Dev Container) on your machine, create a new virtual environment by running: 101 | 102 | ```bash 103 | cd scipy-vscode-tutorial 104 | conda install -n base -c conda-forge mamba 105 | mamba env create -f environment.yml 106 | conda activate tutorial 107 | ``` 108 | 109 | 2. Install the tutorial package by running: 110 | 111 | ```bash 112 | pip install -e . 113 | ``` 114 | 115 | 3. Use the Command Palette to run the `Python: Select Interpreter` command and set it to the `tutorial` environment you just created. 116 | 4. Use the Command Palette to create a new Interactive Window using the `Jupyter: Create Interactive Window` command. 117 | 5. Run the following lines to test your environment: 118 | 119 | ```python 120 | from tutorial import welcome 121 | welcome() 122 | ``` 123 | ```` 124 | -------------------------------------------------------------------------------- /2-devtips.md: -------------------------------------------------------------------------------- 1 | # Scientific Python development tips and tricks 2 | 3 | ## Code navigation 4 | 5 | Learn how to speed up how you navigate through code. 6 | 7 | ### [Sidebar search](https://code.visualstudio.com/docs/editor/codebasics#_search-across-files) 8 | 9 | ![](https://code.visualstudio.com/assets/docs/editor/codebasics/search-replace-example.png) 10 | 11 | Now with more Regex! 12 | 13 | ![](https://code.visualstudio.com/assets/docs/editor/codebasics/case-change-replace.gif) 14 | 15 | If you want to do some really detailed/contextual searching also check out the [Search Editor](https://code.visualstudio.com/docs/editor/codebasics#_search-editor) which allows you to see more context around your search results and open it in a full window: 16 | ![](https://code.visualstudio.com/assets/docs/editor/codebasics/search-editor-overview.png) 17 | 18 | ### Bring your favorite [keymaps](https://code.visualstudio.com/docs/getstarted/keybindings#_keymap-extensions): vim/emacs/sublime/… 19 | 20 | Filter the extension marketplace search with `@category:"keymaps"` to see all the ones folks have contributed. 21 | 22 | ### [Multi-line editing](https://code.visualstudio.com/docs/editor/codebasics#_multiple-selections-multicursor) 23 | 24 | ![](https://code.visualstudio.com/assets/docs/editor/codebasics/multicursor.gif) 25 | 26 | Helpful cheat sheets for keybord shortcuts: [Windows](https://code.visualstudio.com/shortcuts/keyboard-shortcuts-windows.pdf), [Mac](https://code.visualstudio.com/shortcuts/keyboard-shortcuts-macos.pdf), [Linux](https://code.visualstudio.com/shortcuts/keyboard-shortcuts-linux.pdf). 27 | 28 | ```{admonition} Exercise: Explore code navigation 29 | 1. Create a new file `hello.py` in the `tutorial` package with a function `say_hello` that prints a message using the `emoji` library. Use IntelliSense to find the right function and order of input arguments from the library. 30 | 2. Output the text of Zen of Python into a file by running `python -c "import this" > zen_of_python.md`. 31 | 3. Open the file and replace the word "is" with the word "was". How many keystrokes does it take to make this replacement in the editor? 32 | 4. Use regex search to find all sentences that have the pattern `\w+ better than \w+.`. Replace it with `is awesome!`. 33 | 5. Use Alt+ ↑ / ↓ to move the line "Readability counts." to the top. 34 | ``` 35 | 36 | ### [IntelliSense](https://code.visualstudio.com/docs/editor/intellisense) 37 | 38 | Have you ever been typing and a popup with an auto-completion or hint pop up in a menu that you could pick from? 39 | [IntelliSense](https://code.visualstudio.com/docs/editor/intellisense) is a general term for a whole catagory of features like this including: code completion, parameter info, quick info, and member lists. 40 | In VS Code it will automatically pop up as you type for [supported languages](https://code.visualstudio.com/docs/editor/intellisense#_intellisense-for-your-programming-language) or with `Ctrl+Space` | `Cmd+Space`. 41 | If you are not sure what the little icons next to certian suggestions mean, you can see a [legend](https://code.visualstudio.com/docs/editor/intellisense#_types-of-completions) in the docs. 42 | 43 | ![](https://code.visualstudio.com/assets/docs/editor/intellisense/intellisense_docs.gif) 44 | 45 | ```{tip} 46 | There are a lot of customization options for how and when for Intellesense popups to open, check them out here and tweak or even turn off to your hearts content ❤️ 47 | ``` 48 | 49 | IntelliSense is not AI generated, it uses language servers and other fancy diagnostic tools to constantly be analyzing your code to make suggestions. 50 | If you want to try writing code with AI suggestions as well, you can check out [GitHub Copilot](https://code.visualstudio.com/docs/editor/intellisense#_enhance-completions-with-ai) which we will cover in [Chapter 4](4-collaboration.md). 51 | 52 | ```{admonition} Exercise 53 | Try typing some new code in the sample notebook [here](TODO) and see what IntelliSense suggests! 54 | ``` 55 | 56 | ### [Symbol search](https://code.visualstudio.com/Docs/editor/editingevolved#_open-symbol-by-name) 57 | 58 | Helps you look up a particular object/class/method/etc. 59 | 60 | ### [Go To ...](https://code.visualstudio.com/Docs/editor/editingevolved#_go-to-type-definition) 61 | 62 | Quick way to follow clues and solve mysteries. 63 | 64 | ### [Refactoring](https://code.visualstudio.com/docs/editor/refactoring) 65 | 66 | If find all + replace won't work, the refactoring tools like renaming a symbol below are always available. 67 | 68 | ![](https://code.visualstudio.com/assets/docs/editor/refactoring/rename.png) 69 | 70 | ### [Snippets](https://code.visualstudio.com/docs/editor/userdefinedsnippets) 71 | 72 | Type the name of the snippet or an alias and then `tab` to insert. 73 | 74 | ![](https://code.visualstudio.com/assets/docs/editor/userdefinedsnippets/ajax-snippet.gif) 75 | 76 | 77 | ## Running and testing code 78 | 79 | Now that we finally know our way around the editor it’s time to write and test some code! Here we’ll go through a few exercises that let you test the code you’ve written in the previous exercise and debug it. 80 | 81 | ```{tip} 82 | One important concept here is understanding what is the current Python interpreter. This can be set from the command pallet, and is the actual install/environment where VS Code will run your code. 83 | ``` 84 | 85 | ### [Running scripts](https://code.visualstudio.com/docs/python/python-tutorial#_run-hello-world) 86 | 87 | There are a few ways to run Python code in VS Code (other than the terminal 😄): 88 | 89 | 1. Click the Run Python File in Terminal play button in the top-right side of the editor, which opens a terminal and runs it with the selected Python interpreter. 90 | 91 | ![Using the Run Python File in Terminal button](https://code.visualstudio.com/assets/docs/python/tutorial/run-python-file-in-terminal-button.png) 92 | 93 | 2. Right-click anywhere in the editor window and select Run > Python File in Terminal (which saves the file automatically): 94 | 95 | 3. Select one or more lines, then press Shift+Enter or right-click and select Run Selection/Line in Python Terminal. This command is convenient for testing just a part of a file. 96 | 97 | 4. From the Command Palette (Ctrl+Shift+P), select the Python: Start REPL command to open a REPL terminal for the currently selected Python interpreter. 98 | 99 | ### [Test browser extension](https://marketplace.visualstudio.com/items?itemName=LittleFoxTeam.vscode-python-test-adapter) 100 | 101 | Sometimes test files can be overwhelming, this extension can make it easier to look at all of them and supports a variety of test frameworks to use for running tests. 102 | 103 | ![](https://github.com/kondratyev-nv/vscode-python-test-adapter/raw/HEAD/img/screenshot.png) 104 | 105 | ```{admonition} Exercise: Debug code with tests 106 | 1. Create a new folder called `tests` and a new file `test_hello.py`. 107 | 2. Import the functions you've created in the first exercise using `from tutorial.hello import say_hello` and create a new function `test_say_hello` that calls `say_hello`. 108 | 3. Open the "Testing" menu by clicking on the vial icon in the Activity bar, click "Configure Python Tests" and choose "pytest". Pick the `tests` folder. 109 | 4. Run your test by clicking on the "Run Test" ▷ icon. 110 | 5. Add a new `name` input argument to the `say_hello` function. Run your test again. Can you fix the bug? 111 | ``` 112 | 113 | ### [Debugging](https://code.visualstudio.com/Docs/editor/debugging) 114 | 115 | You can start a debug session from the Run + Debug pane on the left. 116 | If you don't have a configuration for your code yet, the gear icon can help set some templates up. 117 | 118 | ![](https://code.visualstudio.com/assets/docs/editor/debugging/debugging_hero.png) 119 | 120 | ## Git and version control in VS Code 121 | 122 | You’ve written some code - it’s time to push it upstream. We’ll go over some exercises that let you use the [built-in Git tools](https://code.visualstudio.com/docs/sourcecontrol/overview) to interact with the repository we cloned in the previous section. 123 | 124 | ### General git 125 | 126 | - checkout, 127 | - branching, 128 | - staging, 129 | - committing, etc. 130 | 131 | ### In-editor features 132 | 133 | - diff in-line 134 | - timeline view 135 | - gutter indicators 136 | 137 | ### When things go wrong 🥲 138 | 139 | - 3-way merge editor 140 | - UI for viewing/managing merge conflicts 141 | - Diff viewer 142 | 143 | ### [GitHub Pull Request and Issues extensions](https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-pull-request-github) 144 | 145 | Stay focused and use all the keybindings you are familiar with by catching up on issues and reviewing PRs directly in VS Code. 146 | 147 | ### [Gitignore extension](https://marketplace.visualstudio.com/items?itemName=codezombiech.gitignore) 148 | 149 | If you don't want to go digging/copying `.gitignore` files from your last project, this extension can provide ones for a variety of languages with just a click. 150 | 151 | ```{admonition} Exercise: Sign our yearbook! 152 | 1. Fork the [tutorial repo](https://aka.ms/scipy2023) to your GitHub account 153 | 2. Edit the file `yearbook2023.md` and add your favorite VS Code tip you've learned so far. Sign it with your GitHub handle. 154 | 3. Create a new branch using the menu `Branch` > `Create branch`, and name it `/yearbook-2023`. 155 | 4. Commit your changes to your new branch and push the changes using `Commit & Push`. 156 | 5. Create a PR to the origin repo, either with the GitHub PR extension or via the GitHub web interface so we can review and merge! 157 | ``` 158 | ` 159 | ## Documentation 160 | 161 | Don't forget to document your work! Here we'll go over some tools in VS Code and GitHub to level up your docs. 162 | 163 | ### LaTeX in VS Code! 164 | 165 | The [LaTeX Workshop](https://marketplace.visualstudio.com/items?itemName=James-Yu.latex-workshop) extension answered the long-standing question: when would LaTeX work be possible in VS Code? 166 | 167 | 168 | ### Sphinx (or similar static generator) 169 | 170 | You can use convenient [GitHub actions](https://github.com/marketplace/actions/deploy-to-github-pages) to push [Read the Docs](https://github.com/readthedocs/actions) or GitHub Pages once test built. 171 | 172 | ### [Markdown linting](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) 173 | 174 | 175 | ```{admonition} Exercise: Document your code 176 | 1. Configure the `autoDocstring` extension to use `sphinx` as its Docstring format. 177 | 2. Add a docstring to the `say_hello` function you created in an earlier exercise. 178 | 3. (Optional) Run `sphinx-quickstart` to set up your Sphinx documentation and follow the steps in this [tutorial](https://github.com/melissawm/minimalsphinx) by @melissawm. 179 | 4. (Optional) Install the LaTeX Workshop extension (requires [TeX live](https://www.tug.org/texlive/)). Create a new folder `docs` with file `about.tex`. Start writing a page in [LaTeX](https://www.colorado.edu/aps/sites/default/files/attached-files/latex_primer.pdf) and explore the IntelliSense features. 180 | ``` 181 | 182 | ## Data science tools 183 | 184 | After writing your code, let’s put it to use. Here we’ll cover some of VS Code’s specialized features for data science, and install some typical extensions that plug into the scientific Python ecosystem. 185 | 186 | ### [Jupyter notebooks:](https://code.visualstudio.com/docs/datascience/jupyter-notebooks) 187 | 188 | - Running with keyboard shortcuts 189 | - Customizing UI 190 | - Outline pane 191 | - Variable + Data viewer 192 | - Kernel selection 193 | - Debugging 194 | - Notebook diffs 195 | - Saving + inserting images 196 | 197 | ### Hot of the presses: [Data wrangler](https://devblogs.microsoft.com/python/data-wrangler-release/) 198 | 199 | A new [extension](https://marketplace.visualstudio.com/items?itemName=ms-toolsai.datawrangler) just a few months new that helps with some of that initial data exploration with cool UI which also can capture what manipulations you make and generate the Pandas code needed to reproduce! 200 | 201 | ![](https://user-images.githubusercontent.com/15910920/222234663-5e8178f8-851f-4326-8719-9d90039ce023.gif) 202 | 203 | ```{admonition} Exercise: Data Science in VS Code 204 | 1. Create a new Data Science profile. 205 | 2. Open the `demo.ipynb` Jupyter Notebook. 206 | 3. Run the example cells in the notebook. Try adding a markdown cell and add some text, or add a code cell. 207 | 4. Open the example data file `data/bees.csv` using Data Wrangler and explore the dataset (source: [Bee-Gap: Ecology, Life-History, and Distribution of Bee Species in the United States 2017](https://www.sciencebase.gov/catalog/item/5bd868b2e4b0b3fc5ce9dadd)). 208 | 209 | Can you figure out which plant species and/or plant family is most loved by all bee species recorded? 210 | ``` 211 | 212 | Awesome, you made it! 213 | Now on to [Chapter 3 ⏩](3-remote.md) 214 | -------------------------------------------------------------------------------- /3-remote.md: -------------------------------------------------------------------------------- 1 | # Interacting with remote resources 2 | 3 | ## Interlude: some background 4 | 5 | The modular design of VS Code lets you choose where to run the user interface and the backend independently. Let's understand how this came to be. 6 | 7 | - [A brief history of VS Code](history.md) 8 | - [VS Code's extension architecture](architecture.md) 9 | 10 | ## The Remote development extension pack 11 | 12 | Developing inside pre-packaged local DevContainers, on a virtual machine in the cloud, in a GitHub Codespace, and more. 13 | 14 | - [WSL](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-wsl): Windows Subsystem for Linux was VS Code's first remote development scenario 15 | - [Remote - SSH](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh): Connect your local VS Code to a remote machine over SSH 16 | - Automatic port forwarding (web apps, Jupyter servers) 17 | - [Remote - Tunnels](https://marketplace.visualstudio.com/items?itemName=ms-vscode.remote-server): Reach remote machines behind firewalls 18 | - On remote machine, open a terminal and run: 19 | ``` 20 | curl -Lk 'https://code.visualstudio.com/sha/download?build=stable&os=cli-alpine-x64' --output vscode_cli.tar.gz 21 | tar -xf vscode_cli.tar.gz 22 | ./code tunnel 23 | ``` 24 | - Connect from Desktop app via `Remote Tunnels: Connect to tunnel` 25 | - [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers): Work inside containers & make your environment reproducible for others 26 | - The [`devcontainer.json`](.devcontainer/devcontainer.json) in this repository follows the [Development Containers standard](https://containers.dev/) 27 | - [GitHub Codespaces](https://github.com/features/codespaces) = Dev Containers hosted by GitHub 28 | 29 | **Exercise** 30 | Play with different UI/backend scenarios, and share with your group, involving them if you can 31 | 32 | Here are some ideas: 33 | 34 | - Contribute a `devcontainer.json` to your favorite repository on GitHub & make it easier for everyone to give the package a try 35 | - Connect remotely to a machine you typically use a command line editor like vim/emacs on 36 | - For tutorial participants: 37 | - Connect to JupyterHub, choose user/password 38 | - Click New => Terminal 39 | - Create a file `.ssh/authorized_keys` and add your SSH public key to it 40 | - Connect to Hub using `jupyter-` at port 2222 41 | - Windows users: install WSL, and use [this trick](https://stackoverflow.com/questions/60150466/can-i-ssh-from-wsl-in-visual-studio-code/66048792#66048792) to have VS Code read your SSH config file from the WSL environment 42 | - Start a GitHub codespace on the `scipy-vscode-tutorial` repository and connect to it from your local VS Code via "Open Codespace in new Window" 43 | - Start a VS Code server (`code tunnel`) on your machine and connect from your tablet / let your neighbor connect 44 | 45 | ## vscode.dev / github.dev 46 | 47 | Everything runs inside your browser 48 | 49 | - Press `.` on any GitHub repo 50 | - [Continue working on](https://code.visualstudio.com/docs/editor/vscode-web#_continue-working-in-a-different-environment) a different device without having to commit 51 | - More "workspace extensions" are coming to vscode.dev 52 | - Already there: LiveShare, some language servers, ... 53 | 54 | **Exercise** 55 | 56 | - There are now 3 different ways to make a pull request to a GitHub repository using just your browser. What are they? 57 | - Try the new [Python for the Web](https://code.visualstudio.com/docs/python/python-web) directly on [insiders.vscode.dev](https://insiders.vscode.dev/) 58 | -------------------------------------------------------------------------------- /4-collaboration.md: -------------------------------------------------------------------------------- 1 | # Working together, but make it cool 2 | 3 | ## Collaboration 4 | 5 | No one really codes alone, and finding the right tools for you and your team is 💯 6 | 7 | ### Pair programming with[ Live Share](https://marketplace.visualstudio.com/items?itemName=MS-vsliveshare.vsliveshare) 8 | 9 | Time for a team huddle, rubber ducks included! 10 | 11 | Live Share is a way to send anyone a URL and have them join you in your VS Code session. 12 | It is easy to configure the permissions for guests, as well as tools to focus or request focus for all participants. 13 | 14 | ```{admonition} Exercise: Do it live (share) 15 | 1. Have one team member post a live share link to their editor to the rest of the group and let folks join. 16 | 2. Make sure all team members have text edit access and each person update your individual yearbook entries now with your team name. 17 | 3. The Live Share host can then commit, push, and PR the changes from the VS Code UI. Note that commit messages should have co-authors auto-added to commit message if they edited the files as well. 18 | ``` 19 | 20 | ## Work with AI for coding 21 | 22 | We’ll go over some new extensions/features of VS Code using GitHub CoPilot. 23 | 24 | ### [GitHub CoPilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot): Your AI pair programmer 25 | 26 | ![](https://user-images.githubusercontent.com/37570492/212964557-8d832278-61bb-4288-a8a7-47f35859e868.gif) 27 | 28 | 29 | Free for students and open-source contributors 30 | 31 | ### [GitHub CoPilot Labs](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot-labs) 32 | 33 | Try out some of the newest features first! 34 | 35 | ![](https://user-images.githubusercontent.com/8978670/160909091-70c1d70c-2850-4483-91ed-4de87efe5285.gif) 36 | 37 | ## Bonus round! 38 | 39 | Here are some fun extensions that can help take the edge off of a busy workday. 40 | 41 | ### [Vscode-pets](https://marketplace.visualstudio.com/items?itemName=tonybaloney.vscode-pets): Good clippy 👍 42 | 43 | ![](https://github.com/tonybaloney/vscode-pets/raw/master/docs/source/_static/pet-in-default-explorer.png) 44 | 45 | ### [Power Mode](https://marketplace.visualstudio.com/items?itemName=hoovercj.vscode-power-mode): ITS OVER 9000 46 | 47 | ![](https://github.com/hoovercj/vscode-power-mode/raw/HEAD/images/demo-v3.gif) 48 | 49 | ### [Music time](https://marketplace.visualstudio.com/items?itemName=softwaredotcom.music-time): Spotify in VS Code 50 | 51 | ![](https://assets.software.com/readme/music-time/vscode/features-2.1.15.png) 52 | 53 | ### [Code tour](https://marketplace.visualstudio.com/items?itemName=vsls-contrib.codetour) 54 | 55 | ![](https://user-images.githubusercontent.com/116461/98431597-bb3f2800-206b-11eb-8f46-55f48ff014ef.gif) 56 | 57 | ## Wrap-up & Epilogue 58 | 59 | It’s time to close out the tutorial and recap everything we’ve learned so far. We also want to end with some final remarks and recommendations. 60 | 61 | ### Recap of features/lessons 62 | 63 | ### Where to learn more and keep up on news 64 | 65 | - [VS Code YouTube](https://www.youtube.com/channel/UCs5Y5_7XK8HLDX0SLNwkd3w) 66 | - [File an issue](https://github.com/Microsoft/vscode/issues) 67 | - [Request a feature](https://github.com/microsoft/vscode/issues/new?assignees=&labels=&projects=&template=feature_request.md) 68 | - [Ask a question on Discord](https://aka.ms/python-discord) 69 | - [Microsoft Developer YouTube](https://www.youtube.com/c/MicrosoftDeveloper) 70 | - [Microsoft Developer Twitch](https://www.twitch.tv/microsoftdeveloper) 71 | - [VS Code Blog RSS feed](https://code.visualstudio.com/feed.xml) 72 | 73 | ### Next: Try out a [tutorial challenge!](challenge.md) 74 | 75 | -------------------------------------------------------------------------------- /CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Contributor Covenant Code of Conduct 2 | 3 | ## Our Pledge 4 | 5 | We as members, contributors, and leaders pledge to make participation in our 6 | community a harassment-free experience for everyone, regardless of age, body 7 | size, visible or invisible disability, ethnicity, sex characteristics, gender 8 | identity and expression, level of experience, education, socio-economic status, 9 | nationality, personal appearance, race, religion, or sexual identity 10 | and orientation. 11 | 12 | We pledge to act and interact in ways that contribute to an open, welcoming, 13 | diverse, inclusive, and healthy community. 14 | 15 | ## Our Standards 16 | 17 | Examples of behavior that contributes to a positive environment for our 18 | community include: 19 | 20 | * Demonstrating empathy and kindness toward other people 21 | * Being respectful of differing opinions, viewpoints, and experiences 22 | * Giving and gracefully accepting constructive feedback 23 | * Accepting responsibility and apologizing to those affected by our mistakes, 24 | and learning from the experience 25 | * Focusing on what is best not just for us as individuals, but for the 26 | overall community 27 | 28 | Examples of unacceptable behavior include: 29 | 30 | * The use of sexualized language or imagery, and sexual attention or 31 | advances of any kind 32 | * Trolling, insulting or derogatory comments, and personal or political attacks 33 | * Public or private harassment 34 | * Publishing others' private information, such as a physical or email 35 | address, without their explicit permission 36 | * Other conduct which could reasonably be considered inappropriate in a 37 | professional setting 38 | 39 | ## Enforcement Responsibilities 40 | 41 | Community leaders are responsible for clarifying and enforcing our standards of 42 | acceptable behavior and will take appropriate and fair corrective action in 43 | response to any behavior that they deem inappropriate, threatening, offensive, 44 | or harmful. 45 | 46 | Community leaders have the right and responsibility to remove, edit, or reject 47 | comments, commits, code, wiki edits, issues, and other contributions that are 48 | not aligned to this Code of Conduct, and will communicate reasons for moderation 49 | decisions when appropriate. 50 | 51 | ## Scope 52 | 53 | This Code of Conduct applies within all community spaces, and also applies when 54 | an individual is officially representing the community in public spaces. 55 | Examples of representing our community include using an official e-mail address, 56 | posting via an official social media account, or acting as an appointed 57 | representative at an online or offline event. 58 | 59 | ## Enforcement 60 | 61 | Instances of abusive, harassing, or otherwise unacceptable behavior may be 62 | reported to the community leaders responsible for enforcement at 63 | sckaiser@sckaiser.com. 64 | All complaints will be reviewed and investigated promptly and fairly. 65 | 66 | All community leaders are obligated to respect the privacy and security of the 67 | reporter of any incident. 68 | 69 | ## Enforcement Guidelines 70 | 71 | Community leaders will follow these Community Impact Guidelines in determining 72 | the consequences for any action they deem in violation of this Code of Conduct: 73 | 74 | ### 1. Correction 75 | 76 | **Community Impact**: Use of inappropriate language or other behavior deemed 77 | unprofessional or unwelcome in the community. 78 | 79 | **Consequence**: A private, written warning from community leaders, providing 80 | clarity around the nature of the violation and an explanation of why the 81 | behavior was inappropriate. A public apology may be requested. 82 | 83 | ### 2. Warning 84 | 85 | **Community Impact**: A violation through a single incident or series 86 | of actions. 87 | 88 | **Consequence**: A warning with consequences for continued behavior. No 89 | interaction with the people involved, including unsolicited interaction with 90 | those enforcing the Code of Conduct, for a specified period of time. This 91 | includes avoiding interactions in community spaces as well as external channels 92 | like social media. Violating these terms may lead to a temporary or 93 | permanent ban. 94 | 95 | ### 3. Temporary Ban 96 | 97 | **Community Impact**: A serious violation of community standards, including 98 | sustained inappropriate behavior. 99 | 100 | **Consequence**: A temporary ban from any sort of interaction or public 101 | communication with the community for a specified period of time. No public or 102 | private interaction with the people involved, including unsolicited interaction 103 | with those enforcing the Code of Conduct, is allowed during this period. 104 | Violating these terms may lead to a permanent ban. 105 | 106 | ### 4. Permanent Ban 107 | 108 | **Community Impact**: Demonstrating a pattern of violation of community 109 | standards, including sustained inappropriate behavior, harassment of an 110 | individual, or aggression toward or disparagement of classes of individuals. 111 | 112 | **Consequence**: A permanent ban from any sort of public interaction within 113 | the community. 114 | 115 | ## Attribution 116 | 117 | This Code of Conduct is adapted from the [Contributor Covenant][homepage], 118 | version 2.0, available at 119 | https://www.contributor-covenant.org/version/2/0/code_of_conduct.html. 120 | 121 | Community Impact Guidelines were inspired by [Mozilla's code of conduct 122 | enforcement ladder](https://github.com/mozilla/diversity). 123 | 124 | [homepage]: https://www.contributor-covenant.org 125 | 126 | For answers to common questions about this code of conduct, see the FAQ at 127 | https://www.contributor-covenant.org/faq. Translations are available at 128 | https://www.contributor-covenant.org/translations. 129 | -------------------------------------------------------------------------------- /LICENCE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2023 Sarah Kaiser 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Meet your coding best friend: VS Code💖 2 | ![Raccon mascot bit in a header image working on a laptop with the title: Meet your coding best friend: VS Code💖](static/image.png) 3 | 4 | _A hands-on tutorial on how to get the most out of the world’s most popular Python editor_ 5 | 6 | > Tutorial for [SciPy 2023](https://cfp.scipy.org/2023/talk/RKV3PZ/), 2023-07-10, 13:30–17:30 (America/Chicago), Classroom 105. 7 | 8 | [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/crazy4pi314/scipy-vscode-tutorial?quickstart=1) 9 | [![Jupyter Book Badge](https://jupyterbook.org/badge.svg)](https://aka.ms/scipy2023) 10 | 11 | Visual Studio Code (VS Code) is a free code editor that runs on Windows, Linux, macOS and in your browser. This tutorial aims at Python programmers of all levels who are already using VS Code or are interested in doing so, and will take them from zero (installing VS Code) to a production setup for Python development. We will cover starter topics, such as customizing the UI and extensions, using code autocomplete, code navigation, debugging, and Jupyter Notebooks. We will also go into advanced use cases, such as remote development, pair programming via Live Share, Dev containers, GitHub Codespaces & more. 12 | 13 | **Checkout the [repo discussions](https://github.com/crazy4pi314/scipy-vscode-tutorial/discussions) for polls, Q&A, and showing off your awesome work!** 14 | 15 | ## Tutorial schedule 16 | 17 | We end each section with a recap to go over everything we’ve covered and an opportunity to ask questions. 18 | 19 | | Time | Duration | Topic | 20 | |-------|----------|------------------------| 21 | | 13:30 | 50 min | [The basics of Python development in VS Code](1-basics.md) | 22 | | 14:20 | 10 min | Break | 23 | | 14:30 | 50 min | [Scientific Python development tips and tricks](2-devtips.md) | 24 | | 15:20 | 10 min | Break | 25 | | 15:30 | 50 min | [Interacting with remote resources](3-remote.md) | 26 | | 16:20 | 10 min | Break | 27 | | 16:30 | 50 min | [Working together, but make it fast](4-collaboration.md) | 28 | | 17:20 | 10 min | Closing remarks | 29 | ## Setup Instructions 30 | 31 | ### **Option 1:** Work on your computer 32 | 33 | 1. [Install VS Code](https://code.visualstudio.com/download) 34 | 2. Install local development environment 35 | 36 | - Variant A: Native installation 37 | - [Install Git](https://github.com/git-guides/install-git) 38 | - [Install Miniconda](https://docs.conda.io/en/latest/miniconda.html) 39 | - Note for Windows users: You may want to [install WSL2](https://learn.microsoft.com/en-us/windows/wsl/install) and install Git and Miniconda in the Linux subsystem. 40 | - Variant B: Use Linux containers. Just [install Docker](https://docs.docker.com/engine/install/) 41 | 42 | 3. Clone this repository: `git clone https://github.com/crazy4pi314/scipy-vscode-tutorial` 43 | 4. Open the repository in VS Code `code scipy-vscode-tutorial` 44 | 5. (Docker only) With your repo open in VS Code, install the [Development Container](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension (if you don't already have it) which will give you command pallet options to re-open the repo in a dev container. 45 | 46 | You should now have the repository open in your local VS Code instance. 47 | 48 | ### **Option 2:** Start instantly in your browser with GitHub Codespaces 49 | 50 | 1. [Create a free GitHub account](https://github.com/join) if you don't have one already 51 | 52 | 1. On the landing page of [this repository](https://github.com/crazy4pi314/scipy-vscode-tutorial), click on the green _Code_ button, and then on the _Codespaces_ tab to create a codespace. 53 | 54 | After a short while you should have a VS Code window in your browser with the repository open. 55 | 56 | This option gives you a fully functional VS Code environment (with [some limitations](https://code.visualstudio.com/docs/remote/codespaces#_known-limitations-and-adaptations)), and should work on laptops and tablets alike. 57 | 58 | > Note: GitHub codespaces come with [120 core-hours and 15 GB-months for free](https://docs.github.com/en/billing/managing-billing-for-github-codespaces/about-billing-for-github-codespaces) for all GitHub accounts (180 core-hours for verified student accounts). 59 | By default, the container running your codespace will have 2 CPU cores, 4 GB of RAM, and 32 GB of local storage. 60 | 61 | ### **Option 3:** Follow along on vscode.dev 62 | 63 | If neither option 1 nor 2 works for you, you can still shadow the presenters in a read-only [LiveShare](https://code.visualstudio.com/learn/collaboration/live-share) session in your web browser. 64 | Contrary to option 2 this does not require a GitHub account - all you need is a web browser. 65 | 66 | We will share a https://vscode.dev/liveshare link at the start of the session. 67 | When opening the link, select "Continue on web" and "Continue as anonymous". 68 | 69 | 70 | ## Structure of this repository 71 | 72 | This repository contains a [Dev Container](https://containers.dev/) setup that provides [conda](https://github.com/conda/conda) and [mamba](https://github.com/mamba-org/mamba) for setting up Python environments. 73 | This repo contains a sample Conda environment file ([environment.yml](environment.yml)), demo Jupyter notebook, and Dev Container configuration files that describe how a containerized development can be built for the repo. 74 | These configuration files work for both local Dev Containers as well as [Codespaces](https://github.com/features/codespaces), a GitHub-hosted cloud environment. 75 | 76 | The Docker setup for the Dev Container starts with a miniconda image that then will install whatever conda environment file you have at the root of the repo. 77 | There are some additional configuration options in the comments of the [Docker](.devcontainer/Dockerfile) and [devcontainer.json](.devcontainer/devcontainer.json) that have some examples of other steps you may want to add to your Dev Container, like what VS Code extensions to install when the container is launched. 78 | 79 | ## References 80 | 81 | * [bees.csv](data/bees.csv): Diller, S.N., Schaeffer, J.S., Grundel, R., Pavlovic, N.B., McKenna, J.E. Jr., Esselman, P.C., 2020, Bee-Gap: Ecology, Life-History, and Distribution of Bee Species in the United States 2017: U.S. Geological Survey data release, https://doi.org/10.5066/P9QHQNNS. 82 | 83 | ## Contributors 84 | 85 | 86 | 87 | 88 | 89 | 90 | 91 | 92 | 93 | -------------------------------------------------------------------------------- /_config.yml: -------------------------------------------------------------------------------- 1 | # Book settings 2 | # Learn more at https://jupyterbook.org/customize/config.html 3 | 4 | title: "Meet your coding best friend: VS Code💖" 5 | author: SciPy 2023 6 | logo: static/vscode-bit.png 7 | # Auto-exclude files not in the toc 8 | only_build_toc_files: false 9 | exclude_patterns: [_build, Thumbs.db, .DS_Store, "**.ipynb_checkpoints", demo.ipynb, .devcontainer, .gitignore, CODE_OF_CONDUCT.md] 10 | 11 | # Force re-execution of notebooks on each build. 12 | # See https://jupyterbook.org/content/execute.html 13 | execute: 14 | execute_notebooks: force 15 | 16 | # Define the name of the latex output file for PDF builds 17 | latex: 18 | latex_documents: 19 | targetname: tutorial.tex 20 | 21 | # Add a bibtex file so that we can create citations 22 | bibtex_bibfiles: 23 | - static/references.bib 24 | 25 | # Information about where the book exists on the web 26 | repository: 27 | url: https://github.com/crazy4pi314/scipy-vscode-tutorial # Online location of your book 28 | # path_to_book: # Optional path to your book, relative to the repository root 29 | branch: main # Which branch of the repository should be used when creating links (optional) 30 | 31 | # Add GitHub buttons to your book 32 | # See https://jupyterbook.org/customize/config.html#add-a-link-to-your-repository 33 | html: 34 | use_issues_button: true 35 | use_repository_button: true 36 | -------------------------------------------------------------------------------- /_toc.yml: -------------------------------------------------------------------------------- 1 | # Table of contents 2 | # Learn more at https://jupyterbook.org/customize/toc.html 3 | 4 | format: jb-book 5 | root: README 6 | parts: 7 | # - caption: Home 8 | # numbered: False 9 | # chapters: 10 | # - file: README 11 | - caption: Chapters 12 | numbered: True 13 | chapters: 14 | - title: The basics 15 | file: 1-basics 16 | - title: Dev tips and tricks 17 | file: 2-devtips 18 | - title: Working remotely 19 | file: 3-remote 20 | sections: 21 | - file: history 22 | - file: architecture 23 | - title: Working together 24 | file: 4-collaboration 25 | - caption: Bonus 26 | numbered: False 27 | chapters: 28 | - title: Challenges 29 | file: challenges 30 | - title: 😎 SciPy 2023 yearbook 31 | file: yearbook2023 32 | -------------------------------------------------------------------------------- /architecture.md: -------------------------------------------------------------------------------- 1 | ## VS Code - client/server architecture 2 | - Graphical user interface can run inside 3 | - Electron app: VS Code Desktop application 4 | - Browser: GitHub Codespace, vscode.dev, github.dev, ... 5 | - Backend can run inside 6 | - Electron app: VS Code Desktop application 7 | - Local WSL: WSL extension 8 | - Remote computer: Remote SSH extension, Tunnel extension 9 | - Local container: Dev Containers extension 10 | - Container hosted by GitHub: GitHub Codespaces 11 | - Browser: vscode.dev, github.dev (limited functionality) 12 | 13 | ### Example - VS Code Desktop with WSL extension 14 | ![VS Code WSL](static/architecture/architecture-wsl.png) 15 | 16 | ### Example - VS Code Desktop with Remote SSH extension 17 | ![VS Code Remote SSH](static/architecture/architecture.png) 18 | 19 | 21 | -------------------------------------------------------------------------------- /challenges.md: -------------------------------------------------------------------------------- 1 | # Bonus Challenges 2 | 3 | If you are looking for more things to try out or are already a pro on the current section, try out one of the suggestions below. 4 | 5 | ```{tip} 6 | Show one of the presenters when you are done for a surprise! 7 | ``` 8 | 9 | ## Make an OSS contribution to VS Code or a VS Code Extension 10 | 11 | Check out the [good first issues](https://github.com/microsoft/vscode/contribute) on the actual VS Code repo itself, the [Python](https://github.com/microsoft/vscode-python/contribute) or [Jupyter](https://github.com/microsoft/vscode-jupyter/contribute) extensions, or on one of your other favorite extension! 12 | 13 | ## Try your hand at making a VS Code Extension 14 | 15 | Maybe there is a feature or tool you wish your VS Code setup would have, now is the time to try! 16 | [Normally the extensions are in Typescript](https://code.visualstudio.com/api/get-started/your-first-extension), but there is [a cool template](https://code.visualstudio.com/api/advanced-topics/python-extension-template) that allows you to use Python to build extensions. 17 | There is also [a great docs page](https://code.visualstudio.com/api/language-extensions/overview) covering the API VS Code exposes for the Python language server. 18 | It doesn't have to be super fancy, but see if you can get a demo extension file to share with someone else to try. 19 | 20 | - [VSCode extension in 60 seconds](https://www.youtube.com/watch?v=6r8pJjylmR4) 21 | - [Building extensions for vscode.dev](https://www.youtube.com/watch?v=sy3TUb_iVJM) 22 | 23 | ## Containerize your favorite project 24 | 25 | Having infrastructure and tools to make OSS projects more reproducible is quite helpful, so let's try and put some more code back in boxes :P 26 | Take a repo that is missing things like Dockerfiles, Devcontainers, or packaging actions and PR them! -------------------------------------------------------------------------------- /demo.ipynb: -------------------------------------------------------------------------------- 1 | { 2 | "cells": [ 3 | { 4 | "cell_type": "code", 5 | "execution_count": null, 6 | "metadata": {}, 7 | "outputs": [], 8 | "source": [ 9 | "import this" 10 | ] 11 | }, 12 | { 13 | "cell_type": "markdown", 14 | "metadata": {}, 15 | "source": [ 16 | "# This is a markdown cell\n", 17 | "\n", 18 | "You can add some notes here.\n", 19 | "\n", 20 | "You can also use LaTeX syntax here!\n", 21 | "\n", 22 | "$\\alpha + \\beta = \\gamma$" 23 | ] 24 | }, 25 | { 26 | "cell_type": "code", 27 | "execution_count": null, 28 | "metadata": {}, 29 | "outputs": [], 30 | "source": [ 31 | "import numpy as np\n", 32 | "import matplotlib.pyplot as plt\n", 33 | "\n", 34 | "plt.plot(np.random.rand(5), \"o-\")" 35 | ] 36 | }, 37 | { 38 | "cell_type": "code", 39 | "execution_count": null, 40 | "metadata": {}, 41 | "outputs": [], 42 | "source": [] 43 | } 44 | ], 45 | "metadata": { 46 | "kernelspec": { 47 | "display_name": "codespaces-mini", 48 | "language": "python", 49 | "name": "python3" 50 | }, 51 | "language_info": { 52 | "codemirror_mode": { 53 | "name": "ipython", 54 | "version": 3 55 | }, 56 | "file_extension": ".py", 57 | "mimetype": "text/x-python", 58 | "name": "python", 59 | "nbconvert_exporter": "python", 60 | "pygments_lexer": "ipython3", 61 | "version": "3.11.4" 62 | }, 63 | "orig_nbformat": 4, 64 | "vscode": { 65 | "interpreter": { 66 | "hash": "f4b37608c0d33d1ba3090d32b4ab60115652e67895fd9c6cef7ce90365731746" 67 | } 68 | } 69 | }, 70 | "nbformat": 4, 71 | "nbformat_minor": 2 72 | } 73 | -------------------------------------------------------------------------------- /docs/about.tex: -------------------------------------------------------------------------------- 1 | \documentclass[12pt]{article} 2 | \title{About this package} 3 | \author{Guen P} 4 | \begin{document} 5 | \maketitle 6 | \section{Section} 7 | Hello, world! 8 | \end{document} -------------------------------------------------------------------------------- /environment.yml: -------------------------------------------------------------------------------- 1 | name: tutorial 2 | channels: 3 | - conda-forge 4 | dependencies: 5 | - python=3.11 6 | - ipykernel # required for jupyter notebook in VS Code 7 | - notebook 8 | - pytest 9 | - matplotlib 10 | - numpy 11 | - pandas 12 | - regex 13 | - pip # if you need more packages installed from pip 14 | - pip: 15 | - emoji 16 | - myst-nb 17 | - jupyter-book 18 | -------------------------------------------------------------------------------- /history.md: -------------------------------------------------------------------------------- 1 | ## [Erich Gamma](https://en.wikipedia.org/wiki/Erich_Gamma) 2 | 3 | ![gamma](static/history/gamma.jpg) 4 | 5 | - Swiss computer scientist 6 | - Co-author of ["Design Patterns: Elements of Reusable Object-Oriented Software"](https://en.wikipedia.org/wiki/Design_Patterns) 7 | - Co-wrote JUnit software testing framework (which helped kickstart test-driven development) 8 | - Lead designer of the Eclipse platform's [Java Development Tools (JDT)](https://eclipse.dev/jdt/) 9 | - Approached by Microsoft in 2011: What can you do with coding in the browser? 10 | 11 | ## [Monaco Editor](https://microsoft.github.io/monaco-editor/) 12 | ![Monaco editor](static/history/monaco.png) 13 | - Lightweight code editor that runs in the browser 14 | - Used by OneDrive, Internet Explorer F12 tools 15 | - Early version with some thousands of users, but developers & platform not ready yet 16 | - 2014: Pivot to desktop via node webkit => VS Code 17 | 18 | 19 | ## VS Code Desktop app 20 | 21 | - First released in 04/2015 22 | - Ships to Windows, Linux, macOS as Electron app (built on top of Chromium and Node.js) 23 | - First Microsoft tool to run on Linux 24 | - Written in TypeScript (started around the same time) 25 | - Only uses standard web APIs, no web frameworks 26 | - Extensions run in separate processes, talk to the main process via remote procedure calls 27 | - Novelty: [Language server protocol](https://microsoft.github.io/language-server-protocol/) (LSP) for language support 28 | - talks only about documents and position => reuse same language server between editors! 29 | - LSP became a standard, [supported by Visual Studio, vim, Emacs, Sublime Text, Atom, ...](https://microsoft.github.io/language-server-protocol/implementors/tools/) 30 | 31 | ## VS Code - license 32 | - [Source code](https://github.com/microsoft/vscode) is MIT licensed (released 11/2015) 33 | - Microsoft's VS Code distribution 34 | - adds Microsoft branding 35 | - turns on telemetry by default 36 | - provides access to extensions marketplace hosted by Microsoft (some extensions are closed source) 37 | - Alternative distributions: 38 | - [VSCodium](https://github.com/VSCodium/vscodium#why): desktop build without Microsoft branding & telemetry, uses [open-vsx.org marketplace](https://open-vsx.org) 39 | - [code-server](https://github.com/coder/code-server): VS Code in the browser built by coder.com 40 | - [OpenVSCode-server](https://github.com/gitpod-io/openvscode-server): VS Code in the browser built by Gitpod 41 | - ... 42 | 43 | 44 | ## VS Code - the open source project 45 | - \>10 years of development, >1M lines of code 46 | - Thousands of issues opened every month 47 | - Team goal: reply within 24 hours 48 | - Monthly release cycle 49 | ![release cycle](static/history/ship-schedule.png) 50 | - Team (2020): 36 = 25 engineers, 6 program managers, 2 doc writers, 1 designer, 1 marketing, 1 UX researcher 51 | 52 | - Watch later: [How we make VS Code in the open](https://www.youtube.com/watch?v=-Olo7N9xwV8) -------------------------------------------------------------------------------- /pyproject.toml: -------------------------------------------------------------------------------- 1 | [project] 2 | name = "tutorial" 3 | description = "SciPy 2023 VS Code tutorial" 4 | version = "0.1.0" -------------------------------------------------------------------------------- /src/tutorial/__init__.py: -------------------------------------------------------------------------------- 1 | import emoji 2 | 3 | def welcome(): 4 | print(emoji.emojize("Meet your coding best friend: VS Code :sparkling_heart:")) 5 | -------------------------------------------------------------------------------- /static/architecture/architecture-wsl.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/crazy4pi314/scipy-vscode-tutorial/c969f463917ac04065bb4911bd03bfb19cc48405/static/architecture/architecture-wsl.png -------------------------------------------------------------------------------- /static/architecture/architecture.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/crazy4pi314/scipy-vscode-tutorial/c969f463917ac04065bb4911bd03bfb19cc48405/static/architecture/architecture.png -------------------------------------------------------------------------------- /static/architecture/extensions.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/crazy4pi314/scipy-vscode-tutorial/c969f463917ac04065bb4911bd03bfb19cc48405/static/architecture/extensions.png -------------------------------------------------------------------------------- /static/history/gamma.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/crazy4pi314/scipy-vscode-tutorial/c969f463917ac04065bb4911bd03bfb19cc48405/static/history/gamma.jpg -------------------------------------------------------------------------------- /static/history/json-rpc.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/crazy4pi314/scipy-vscode-tutorial/c969f463917ac04065bb4911bd03bfb19cc48405/static/history/json-rpc.png -------------------------------------------------------------------------------- /static/history/monaco.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/crazy4pi314/scipy-vscode-tutorial/c969f463917ac04065bb4911bd03bfb19cc48405/static/history/monaco.png -------------------------------------------------------------------------------- /static/history/ship-schedule.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/crazy4pi314/scipy-vscode-tutorial/c969f463917ac04065bb4911bd03bfb19cc48405/static/history/ship-schedule.png -------------------------------------------------------------------------------- /static/image.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/crazy4pi314/scipy-vscode-tutorial/c969f463917ac04065bb4911bd03bfb19cc48405/static/image.png -------------------------------------------------------------------------------- /static/logo-light.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/crazy4pi314/scipy-vscode-tutorial/c969f463917ac04065bb4911bd03bfb19cc48405/static/logo-light.png -------------------------------------------------------------------------------- /static/logo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/crazy4pi314/scipy-vscode-tutorial/c969f463917ac04065bb4911bd03bfb19cc48405/static/logo.png -------------------------------------------------------------------------------- /static/references.bib: -------------------------------------------------------------------------------- 1 | --- 2 | --- 3 | 4 | @inproceedings{holdgraf_evidence_2014, 5 | address = {Brisbane, Australia, Australia}, 6 | title = {Evidence for {Predictive} {Coding} in {Human} {Auditory} {Cortex}}, 7 | booktitle = {International {Conference} on {Cognitive} {Neuroscience}}, 8 | publisher = {Frontiers in Neuroscience}, 9 | author = {Holdgraf, Christopher Ramsay and de Heer, Wendy and Pasley, Brian N. and Knight, Robert T.}, 10 | year = {2014} 11 | } 12 | 13 | @article{holdgraf_rapid_2016, 14 | title = {Rapid tuning shifts in human auditory cortex enhance speech intelligibility}, 15 | volume = {7}, 16 | issn = {2041-1723}, 17 | url = {http://www.nature.com/doifinder/10.1038/ncomms13654}, 18 | doi = {10.1038/ncomms13654}, 19 | number = {May}, 20 | journal = {Nature Communications}, 21 | author = {Holdgraf, Christopher Ramsay and de Heer, Wendy and Pasley, Brian N. and Rieger, Jochem W. and Crone, Nathan and Lin, Jack J. and Knight, Robert T. and Theunissen, Frédéric E.}, 22 | year = {2016}, 23 | pages = {13654}, 24 | file = {Holdgraf et al. - 2016 - Rapid tuning shifts in human auditory cortex enhance speech intelligibility.pdf:C\:\\Users\\chold\\Zotero\\storage\\MDQP3JWE\\Holdgraf et al. - 2016 - Rapid tuning shifts in human auditory cortex enhance speech intelligibility.pdf:application/pdf} 25 | } 26 | 27 | @inproceedings{holdgraf_portable_2017, 28 | title = {Portable learning environments for hands-on computational instruction using container-and cloud-based technology to teach data science}, 29 | volume = {Part F1287}, 30 | isbn = {978-1-4503-5272-7}, 31 | doi = {10.1145/3093338.3093370}, 32 | abstract = {© 2017 ACM. There is an increasing interest in learning outside of the traditional classroom setting. This is especially true for topics covering computational tools and data science, as both are challenging to incorporate in the standard curriculum. These atypical learning environments offer new opportunities for teaching, particularly when it comes to combining conceptual knowledge with hands-on experience/expertise with methods and skills. Advances in cloud computing and containerized environments provide an attractive opportunity to improve the effciency and ease with which students can learn. This manuscript details recent advances towards using commonly-Available cloud computing services and advanced cyberinfrastructure support for improving the learning experience in bootcamp-style events. We cover the benets (and challenges) of using a server hosted remotely instead of relying on student laptops, discuss the technology that was used in order to make this possible, and give suggestions for how others could implement and improve upon this model for pedagogy and reproducibility.}, 33 | booktitle = {{ACM} {International} {Conference} {Proceeding} {Series}}, 34 | author = {Holdgraf, Christopher Ramsay and Culich, A. and Rokem, A. and Deniz, F. and Alegro, M. and Ushizima, D.}, 35 | year = {2017}, 36 | keywords = {Teaching, Bootcamps, Cloud computing, Data science, Docker, Pedagogy} 37 | } 38 | 39 | @article{holdgraf_encoding_2017, 40 | title = {Encoding and decoding models in cognitive electrophysiology}, 41 | volume = {11}, 42 | issn = {16625137}, 43 | doi = {10.3389/fnsys.2017.00061}, 44 | abstract = {© 2017 Holdgraf, Rieger, Micheli, Martin, Knight and Theunissen. Cognitive neuroscience has seen rapid growth in the size and complexity of data recorded from the human brain as well as in the computational tools available to analyze this data. This data explosion has resulted in an increased use of multivariate, model-based methods for asking neuroscience questions, allowing scientists to investigate multiple hypotheses with a single dataset, to use complex, time-varying stimuli, and to study the human brain under more naturalistic conditions. These tools come in the form of “Encoding” models, in which stimulus features are used to model brain activity, and “Decoding” models, in which neural features are used to generated a stimulus output. Here we review the current state of encoding and decoding models in cognitive electrophysiology and provide a practical guide toward conducting experiments and analyses in this emerging field. Our examples focus on using linear models in the study of human language and audition. We show how to calculate auditory receptive fields from natural sounds as well as how to decode neural recordings to predict speech. The paper aims to be a useful tutorial to these approaches, and a practical introduction to using machine learning and applied statistics to build models of neural activity. The data analytic approaches we discuss may also be applied to other sensory modalities, motor systems, and cognitive systems, and we cover some examples in these areas. In addition, a collection of Jupyter notebooks is publicly available as a complement to the material covered in this paper, providing code examples and tutorials for predictive modeling in python. The aimis to provide a practical understanding of predictivemodeling of human brain data and to propose best-practices in conducting these analyses.}, 45 | journal = {Frontiers in Systems Neuroscience}, 46 | author = {Holdgraf, Christopher Ramsay and Rieger, J.W. and Micheli, C. and Martin, S. and Knight, R.T. and Theunissen, F.E.}, 47 | year = {2017}, 48 | keywords = {Decoding models, Encoding models, Electrocorticography (ECoG), Electrophysiology/evoked potentials, Machine learning applied to neuroscience, Natural stimuli, Predictive modeling, Tutorials} 49 | } 50 | 51 | @book{ruby, 52 | title = {The Ruby Programming Language}, 53 | author = {Flanagan, David and Matsumoto, Yukihiro}, 54 | year = {2008}, 55 | publisher = {O'Reilly Media} 56 | } 57 | -------------------------------------------------------------------------------- /static/setting-json-tip.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/crazy4pi314/scipy-vscode-tutorial/c969f463917ac04065bb4911bd03bfb19cc48405/static/setting-json-tip.png -------------------------------------------------------------------------------- /static/vscode-bit.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/crazy4pi314/scipy-vscode-tutorial/c969f463917ac04065bb4911bd03bfb19cc48405/static/vscode-bit.png -------------------------------------------------------------------------------- /yearbook2023.md: -------------------------------------------------------------------------------- 1 | # SciPy 2023 yearbook 2 | 3 | Sign our yearbook! Add your totally awesome team name and your favorite VS Code tip so everyone can see how cool you are 😎 4 | 5 | - [Indent rainbow](https://marketplace.visualstudio.com/items?itemName=oderwat.indent-rainbow): use colors to visualize indentation levels. - @ltalirz 6 | - [Gremlins tracker](https://marketplace.visualstudio.com/items?itemName=nhoizey.gremlins): find that naughty Unicode dash / quote / ... character that breaks your code - @ltalirz 7 | - When editing VS Code settings in JSON, there is a pencil in the gutter which shows you a drop-down menu of valid setting values (if appropriate). - @crazy4pi314 8 | ![Screenshot of a JSON editor window with a pencil icon in the gutter which has a drop down for the valid setting values for that line.](static/setting-json-tip.png) 9 | - The [Witch Hazel by Thea Codes](https://marketplace.visualstudio.com/items?itemName=TheaFlowers.witch-hazel) and [GitHub](https://marketplace.visualstudio.com/items?itemName=GitHub.github-vscode-theme) themes.. - @crazy4pi314 10 | - What all the buttons in the right-hand menu mean - @jryon 11 | - I liked learning about the timeline that has both git commits and save points for the files - @bjcubsfan 12 | - HTRI: the version control tools are neat - @noahbittner 13 | - I am pretty new to VS code. It seems like there is a bit of a steep learning curve to figure out some of the cooler features. Favorite aspect thus far: I like that I can run a terminal, test code and run Jupyter session all in one space. - @rhiannong123 14 | - regex search/replace and multiline editing will both be big time savers! @syd-pythonic 15 | - [GitLens](https://marketplace.visualstudio.com/items?itemName=eamodio.gitlens) used to be kind of a bit much when I wanted to just have a `git blame` function, but now they moved it to its own extension option and it's a lot better now. - @anzelpwj 16 | - Dont leave VCcode in your downloads folder for over a year. - @jeffotter 17 | - Snippets are fun (confusing fun for now) - @yutik-nn 18 | - Found about regex, looking forward to use them working on future projects. - @VadimBim 19 | --------------------------------------------------------------------------------