Add VS Code guide (pypa#1403)

Co-authored-by: Ofek Lev <[email protected]>

docs/blog/.authors.yml

@@ -3,3 +3,7 @@ authors:
     name: Ofek Lev
     description: Creator
     avatar: https://avatars.githubusercontent.com/u/9677399
+  flying-sheep:
+    name: Phil A.
+    description: Contributor
+    avatar: https://avatars.githubusercontent.com/u/291575

docs/blog/posts/release-hatch-1100.md

@@ -1,6 +1,6 @@
 ---
 date: 2024-04-18
-authors: [ofek]
+authors: [ofek,flying-sheep]
 description: >-
   Hatch v1.10.0 brings a test command, support for UV, and a Python script runner.
 categories:
@@ -102,6 +102,8 @@ Additionally, Ruff has been updated to version 1.4.0 and the rules selected by d
 
 Visual Studio Code [announced support](https://code.visualstudio.com/updates/v1_88#_hatch-environment-discovery) for Hatch environments in their latest release. This means that you can now easily discover and select Hatch environments for your projects directly from the editor.
 
+See the [how-to guide](../../how-to/integrate/vscode.md) detailed instructions.
+
 ### CMake build plugin
 
 The extension module builder [scikit-build-core](https://github.com/scikit-build/scikit-build-core) has introduced a [build plugin](https://scikit-build-core.readthedocs.io/en/latest/plugins/hatchling.html) for Hatchling. This means that you can use Hatchling as your build backend while also shipping extension modules built with CMake.

docs/how-to/integrate/vscode.md

@@ -0,0 +1,39 @@
+# How to use Hatch environments from Visual Studio Code
+
+-----
+
+Visual Studio Code announced support for [Hatch environment discovery](https://code.visualstudio.com/updates/v1_88#_hatch-environment-discovery) in `vscode-python`'s [2024.4 release](https://github.com/microsoft/vscode-python/releases/tag/v2024.4.0).
+
+For it to work, you should [install Hatch](../../install.md) globally. If you used the GUI installers on Windows or macOS, or your system package manager on e.g. Arch Linux or Fedora, this should be taken care of.
+
+??? note "Setting up PATH"
+
+    If you installed Hatch with [pipx](../../install.md#pipx) rather than system-wide, you might need to add `$HOME/.local/bin` to your PATH environment variable *for your graphical session*, not just your terminal. Check like this:
+
+    ```console
+    $ pgrep bin/code  # or some other graphical application
+    1234
+    $ cat /proc/1234/environ | tr '\0' '\n' | grep -E '^PATH='
+    PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
+    ```
+
+    If the directory is not in there, you need to add it in your session startup script, in a way that depends on your desktop environment:
+
+    - [KDE Plasma](https://userbase.kde.org/Session_Environment_Variables)
+    - [GNOME](https://help.ubuntu.com/community/EnvironmentVariables#Session-wide_environment_variables)
+
+## Project setup
+
+1. Make Hatch install the project and its dependencies to an environment using the [`env create`](../../cli/reference.md#hatch-env-create) command.
+
+2. Select an interpreter using the ++"Python: Select Interpreter"++ command:
+
+     <figure markdown>
+         ![Select interpreter](./vscode/select-interpreter.png){ loading=lazy role="img" }
+     </figure>
+
+3. You should now be able to use the environment. For example, if you have the `python.terminal.activateEnvironment` setting set to `true` and you open a new terminal, the environment should be activated. Alternatively, you could press the "play" button to run a file in the environment:
+
+     <figure markdown>
+         ![Run file](./vscode/run-file.png){ loading=lazy role="img" }
+     </figure>

mkdocs.yml

@@ -120,6 +120,8 @@ nav:
   - How-to:
     - Meta:
       - Report issues: how-to/meta/report-issues.md
+    - Integrate:
+      - Visual Studio Code: how-to/integrate/vscode.md
     - Run:
       - Python scripts: how-to/run/python-scripts.md
     - Config: