Improve Codespaces documentation

[StevenMaude]

#1268 (comment)

I think ultimately this page is serving three current purposes, and would eventually split into:

• the Getting Started page (but with some extra tidying/refinement)
• a separate page on managing Codespaces and Codespaces billing
• a separate page on the full set of features we provide in the Codespaces setup

It's fine as one self-contained page for now, until we work this out.

#1268 (comment)

Things that aren't discussed in this documentation, or have been thought too much about. They could be considered more in future:

• codespace prebuilds
  • These speed up the codespace deployment, but not sure how these would work inside an organization.
  • Not sure how these interact with template-created repositories either.
  • They cost money for an organization, because they use storage.
• debugging issues with Codespaces
  • can users access Codespaces at all, or does IT policy prevent access?
  • GitHub still occasionally has big outages unfortunately, roughly 1-3 times per month; check GitHub's status page if Codespaces is unavailable or behaving strangely
• more on configuring machines appropriately
  • how to spot out of memory errors
• the "unpublished changes" warning when deleting a codespace
  • you can save these changes to a branch when deleting a codespace
• hiding unhelpful ehrQL autocompletion suggestions of internal attributes/methods
  • not sure how we do this in Visual Studio Code: Support hiding "private" variables/attributes for auto complete microsoft/pylance-release#5281
• keeping the installed ehrQL in sync with the ehrQL version you're using for your project
  • for now, I've not worried about this too much and it's a bit out of scope
  • the latest main version gets installed
  • we might solve it by having a v1, v2 branch, or publishing an ehrQL package to PyPI
  • not sure what the behaviour is on restarting the existing codespace;
    • it might reinstall packages as this is a post-container command, and needs checking
• updating OpenSAFELY CLI
  • may not really need to do manually; you might be able to just stop and start the codespace?
• use of Codespaces with a local Visual Studio Code installation
  • it removes the web browser, which again might help to remove quirks/bugs
  • you can install Visual Studio Code as a "user setup", without admin permissions, I think

[StevenMaude]

Also Codespaces has an actual management panel.

[StevenMaude]

Even though we haven't added everything here, I think this can be considered complete, following the Codespaces initiative earlier this year. If there's more to add that we learn from user feedback, we can open specific issues.