feat: add vscode how-to page

Author: wakonig

docs/how-to/general/vscode.md

@@ -0,0 +1,66 @@
+---
+related:
+  - title: Add Changes to Your Plugin
+    url: how-to/git/add-changes-to-plugin-repository.html
+  - title: Install BEC Locally
+    url: how-to/general/install-bec-locally.html
+---
+
+# Work with VS Code
+
+!!! Info "Overview"
+    This is a how-to guide on using VS Code for working with your BEC plugin.
+
+## Prerequisites
+
+- You have write access to your beamline plugin directory, for example `/sls/<xname>/config/bec/production/<plugin_name>`.
+- If you don't have write access, you can still use VS Code to create and edit files outside of the deployment but you cannot modify the plugin repository directly.
+
+## Open VS Code in the correct folder
+
+Opening the correct folder is important for VS Code to work well. We highly recommend opening the deployment directory:
+
+/// tab | Template
+```bash
+cd /sls/<xname>/config/bec/<deployment_name>
+code .
+```
+///
+
+/// tab | Example
+```bash
+cd /sls/x01da/config/bec/production
+code .
+```
+///
+
+This ensures that VS Code finds the already prepared settings.json file with the correct Python environment.
+
+<figure markdown="span" style="padding: 0.75rem 0;">
+  ![RecommendedExtensions](./vscode_assets/vscode_startup.png){width="90%"}
+</figure>
+
+## Install recommended extensions
+
+When you open the deployment folder, VS Code will prompt you to install recommended extensions. We recommend installing them.
+
+<figure markdown="span" style="padding: 0.75rem 0;">
+  ![RecommendedExtensions](./vscode_assets/vscode_startup_extensions.png){width="90%"}
+</figure>
+
+
+This will give you access to Python language support, formatters, linters but also H5Web for previewing HDF5 files.
+
+
+## Common Pitfalls
+
+- If Python syntax highlighting and auto-completion are not working, check that you have the Python extension installed and that the correct directory is open.
+- If you cannot edit files in the deployment, check that you have write access to the deployment directory. Experiment accounts usually do not have write access to the production deployment, so you may need to log in with your personal account.
+
+## Next Steps
+
+- Continue with [Add Changes to Your Plugin](../git/add-changes-to-plugin-repository.md) if you
+  want to commit and push your changes.
+
+!!! success "Congratulations!"
+    You have successfully set up VS Code for working with your BEC plugin.

docs/how-to/general/vscode_assets/vscode_startup.png

@@ -38,9 +38,10 @@ nav = [
     "how-to/index.md",
     { "Setup and Maintenance" = [
       { "Update BEC" = "how-to/general/update-deployment.md" },
+      { "Work with VS Code" = "how-to/general/vscode.md" },
       { "Add Changes to Your Plugin" = "how-to/git/add-changes-to-plugin-repository.md" },
       { "Merge Changes to main" = "how-to/git/merge-changes-to-main.md" },
-      { "Set the Active Account" = "how-to/general/set-the-active-account-with-bec-set-account.md" }, 
+      { "Set the Active Account" = "how-to/general/set-the-active-account-with-bec-set-account.md" },
       { "Connect to the BEC VM" = "how-to/general/connect-to-the-bec-vm-with-xfreerdp.md" },
       { "Install BEC Locally" = "how-to/general/install-bec-locally.md" },
     ] },
@@ -62,29 +63,29 @@ nav = [
       ] },
     ] },
     { "Devices" = [
-        { "Usage" = [
+      { "Usage" = [
         { "Adding Devices" = [
           { "Add an EPICS Motor" = "how-to/devices/add-an-epics-motor.md" },
           { "Add an EPICS Signal" = "how-to/devices/add-an-epics-signal.md" },
           { "Add a Pseudo Positioner" = "how-to/devices/add-a-pseudo-motor.md" },
         ] },
         { "Configs and Session" = [
-        { "Inspect the Current Device Session" = "how-to/devices/inspect-the-current-device-session-from-the-bec-ipython-client.md" },
-        { "Inspect a Device from the BEC IPython Client" = "how-to/devices/inspect-a-device-from-the-bec-ipython-client.md" },
-        { "Load and Save a Device Session" = "how-to/devices/load-and-save-a-device-session-from-the-bec-ipython-client.md" },
-        { "Change Config Signals from the BEC IPython Client" = "how-to/devices/change-config-signals-from-the-bec-ipython-client.md" },
-        { "Validate a YAML configuration" = "how-to/devices/validate-a-yaml-config-file.md" },
-      ] },
-        ]},
-      { "Development" = [  
-      { "Readout Behavior" = [
-        { "Select a Signal Kind" = "how-to/devices/how-to-select-an-ophyd-kind.md" },
-        { "Select a Readout Priority" = "how-to/devices/how-to-select-readout-priority.md" },
+          { "Inspect the Current Device Session" = "how-to/devices/inspect-the-current-device-session-from-the-bec-ipython-client.md" },
+          { "Inspect a Device from the BEC IPython Client" = "how-to/devices/inspect-a-device-from-the-bec-ipython-client.md" },
+          { "Load and Save a Device Session" = "how-to/devices/load-and-save-a-device-session-from-the-bec-ipython-client.md" },
+          { "Change Config Signals from the BEC IPython Client" = "how-to/devices/change-config-signals-from-the-bec-ipython-client.md" },
+          { "Validate a YAML configuration" = "how-to/devices/validate-a-yaml-config-file.md" },
+        ] },
       ] },
-      { "Simulation" = [
-        { "Use Simulated Models from the IPython Client" = "how-to/devices/use-simulated-models-from-ipython.md" },
+      { "Development" = [
+        { "Readout Behavior" = [
+          { "Select a Signal Kind" = "how-to/devices/how-to-select-an-ophyd-kind.md" },
+          { "Select a Readout Priority" = "how-to/devices/how-to-select-readout-priority.md" },
+        ] },
+        { "Simulation" = [
+          { "Use Simulated Models from the IPython Client" = "how-to/devices/use-simulated-models-from-ipython.md" },
+        ] },
       ] },
-      ]}
     ] },
     { "Data Access" = [
       { "Access BEC History" = "how-to/scans/access-bec-history.md" },
@@ -108,21 +109,21 @@ nav = [
       { "Concepts" = [
         { "Introduction to ophyd" = "learn/devices/introduction-to-ophyd.md" },
         { "Device Sessions" = "learn/devices/device-sessions-in-bec.md" },
-      ]},
+      ] },
       { "Usage" = [
         { "Ophyd Kind Values" = "learn/devices/ophyd-kinds.md" },
         { "Readout Priority" = "learn/devices/readout-priority.md" },
         { "Device Config" = "learn/devices/device-config-in-bec.md" },
-        { "Error Handling during Session Updates" = "learn/devices/error-handling-during-session-updates.md"},
+        { "Error Handling during Session Updates" = "learn/devices/error-handling-during-session-updates.md" },
         { "Managing YAML Configs" = "learn/devices/managing-yaml-configs.md" },
         { "EPICS Motor Variants" = "learn/devices/epics-motors.md" },
         { "EPICS Signal Variants" = "learn/devices/epics-signals.md" },
-      ]},
+      ] },
       { "Development" = [
         { "Pseudo Positioners" = "learn/devices/pseudo-positioners.md" },
         { "BEC Signals" = "learn/devices/bec-signals.md" },
         { "Simulated Devices" = "learn/devices/simulated-devices.md" },
-      ]},
+      ] },
     ] },
     #{ "Scans and execution" = [ TODO fill with content
     #] },