Build out our developer docs

[SydneyhSmith]

Prerequisites

• I have written a descriptive issue title.
• I have searched all issues to ensure it has not already been reported.

Summary

• Update developer/contributor docs to ensure accurate
• Create diagram of PSES/VSCode high level architecture
• Update PSES guide/docs https://github.com/PowerShell/PowerShellEditorServices/tree/master/docs
• Update PSES API reference with more detail https://github.com/PowerShell/PowerShellEditorServices/blob/master/docs/api/index.md

Proposed Design

No response

[JustinGrote]

On the architecture document, it may be worth using Mermaid markdown to render a few diagrams since it is now supported in Github

[fflaten]

If it's possible to debug both extension and PSES in devcontainer, please add it to contributor-doc.

I struggled with debugging PSES last time I tried it (using workspace + .devcontainer in a parent folder). Wouldn't attach IIRC.

[andyleejordan]

I have never used devcontainer. Probably not possible right now, and the files should be deleted. I just use the workspace debug configurations I added, they work like a charm. Make sure you open the workspace file.

[JustinGrote]

PSES is doable standalone in devcontainer, the extension is very unlikely to be able to however since you can't start GUI apps easily in a container.

[fflaten]

I believe I got the extension debugging to work, just not PSES linked to it. That's how I've worked with Tyler's inline-values extension. Both debug and vscode-tests work fine. 🙂

The extension host opens in the devcontainer, but it can be a little unstable if you have to change folder/workspace though. Often have to restart debugging after but then it's fine.

[andyleejordan]

I updated the build scripts so if you're building from the task (or really, in "Debug" configuration, and not release) from a clean slate, it'll symlink the server build to the client so that when the client starts, it is always using your dev build; hence debugging should work with it like a charm. You run "Launch Extension" and then while that debug session is active, you run "Attach to Editor Services" and pick the pwsh process in the launched extension. You can set WaitForDebugger in your Code settings if you need to debug something in the startup sequence.

[fflaten]

Thanks @andschwa ! Got it to work this time, both typescript and C# breakpoints. 🎉

1. Clone PowerShellEditorServices (because it had a devcontainer) in container volume
2. Update devcontainer to new image etc. + Rebuild
3. Clone vscode-powershell in /workspaces in container
4. code-insiders ./vscode-powershell/extension-dev.code-workspace
5. Install .NET runtime 3.1, platyPS, Invoke-Build and build PSES
6. Run build task in VSCode
7. Launch Extension, trigger PSIC and get pid. Attach to Editor Services to pid.

Should have started with cloning vscode-powershell since the PSES devcontainer was too old to be useful. 😄

[andyleejordan]

Hey nice! I will not delete the devcontainer then 😏

[fflaten]

Could probably remove the outdated one in PSES and rather add a compatible devcontainer + guide in this repo since it has the workspace-file.

It's not the best experience, but good enough for us that don't want tons of devtools on the main computer for contributing now and then.

Tip: Adding a folder-path (to your work/demo/debug-folder) as argument in the Launch Extension-task makes it more stable as you probably won't have to use Open Folder. Changing folders/workspaces in the extension host usually de-attaches debugger, reopens a previous project workspace or something else (fun).