Gitpod instructions

[reshamas]

What is this PR about?
Towards #180
Towards #6215

Checklist

• Explain important implementation details 👆
• Make sure that the pre-commit linting/style checks pass.
• Link relevant issues (preferably in nice commit messages)
• Are the changes covered by tests and docstrings?
• Fill out the short summary sections 👇

Documentation

• Update GitPod instructions: https://gitpod.io/#https://github.com/pymc-devs/pymc

Notes

Image tries that do not work

<!-- ![gitpod-integration](gitpod/gitpod_integration.png) -->

<!-- <img src="gitpod/gitpod_integration.png" width="50%" height="50%">
->  

::::{grid-item-card} Gitpod and GitHub Integration
:img-top: gitpod/gitpod_integration.png

::::

NOT TESTED: Ben's notes

Using VSCode Locally on Computer

It is possible to open the Gitpod session directly in VS Code, which may be desirable for people with low-bandwidth connections. Visit https://gitpod.io/workspaces, click "New Workspace", in Context URL type github.com/pymc-devs/pymc. Under Editor select "VS Code - Desktop", and click the "New Workspace" button. After some time a link will be generated which can be opened to launch VS Code. Then click "Yes, I trust the authors".

Running VSC Locally

Notes:

<p><a href="https://gitpod.io/#https://github.com/jupyterlab/jupyterlab"><img src="https://gitpod.io/button/open-in-gitpod.svg" alt="Open in Gitpod"></a></p>
``` 

<br class="Apple-interchange-newline">

[reshamas]

cc: @SangamSwadiK

[maresb]

Looks good to me! I think this is ready to merge. Note that there are many directions in which this could be expanded...

1. It's possible to open directly in VS Code, which may be desirable for people with low-bandwidth connections. Visit https://gitpod.io/workspaces, click "New Workspace", in Context URL type github.com/pymc-devs/pymc. Under Editor select "VS Code - Desktop", and click the "New Workspace" button. After some time a link will be generated which can be opened to launch VS Code. Then click "Yes, I trust the authors". Open question: is there an even simpler way?
2. It should be possible to share a workspace in the style of Google Docs so that multiple people can edit the same files simultaneously. In pure non-GitPod VS Code this feature is called "Live Share". Can this be achieved easily with GitPod? Is there interoperability between the browser version and the "desktop" version? I started investigating this a bit with @rowangayleschaefer.

Also some general things to test: do the credentials get configured correctly for committing and pushing? Are the plugins configured in a sensible way? Do the pre-commit hooks run smoothly?

[reshamas]

@maresb
RE: Liveshare
I spent quite a bit of time with @jmloyola testing LiveShare outside of Gitpod. There is a blog and video on how to use it.
It's an advanced feature, which I think is "nice to have", but not urgent at the moment.
https://blog.dataumbrella.org/pair-programming-with-visual-studio-code-live-share

RE: Git
This is important to have working. I tried to submit this PR from Gitpod and had issues. I tried with the terminal. There is the option to submit a PR within VSC. Not sure if someone else was able to get it working.

[maresb]

Ya, it's not so useful without Git.

I tried, and I managed to get it working. Here's the trick that worked for me...

Go to:
https://www.gitpod.io/docs/configure/authentication/github#granting-additional-github-oauth-permissions
and grant not only public_repo, and repo, but also workflow. (This is because the pymc repo contains files in .github/workflows which require special permissions.)

Next:
Users will need to push to their clone of PyMC, not the main pymc-devs repo. For this we might need to alter the instructions on this PR. Perhaps the first steps are to clone the repo, and to alter the URL by replacing pymc-devs by the user's GitHub username. Or maybe the user should configure their repo and/or the pymc-devs repo as remotes. (Someone needs to work out these details.)

[reshamas]

Some notes after testing with @SangamSwadiK

1. Fork PyMC
2. Create an account on Gitpod
3. User settings/ integrations: edit permissions https://www.gitpod.io/docs/configure/authentication/github#granting-additional-github-oauth-permissions
   and grant not only public_repo, and repo, but also workflow. (This is because the pymc repo contains files in .github/workflows which require special permissions.)
4. Create a new gitpod Dashboard / Workspace / New Workspace / select your forked repo under "Context URL"
5. Note: for git functionality, it requires use of a public email address
6. Get into Gitpod from user's forked repo

[reshamas]

Not sure if this is needed:
https://github.com/apps/gitpod-io

[reshamas]

@maresb
Added info related to workspace: stopping, deletion, pinning.

[maresb]

Excellent work! Just a few minor comments.

[OriolAbril]

Suggested change

	* Check version of pymc: `pip list | grep pymc`
	Example:
	a) Check version of pymc: `pip list | grep pymc`. Example:

This might be a bit more consistent with the sub items above. Otherwise, the "Example" and code lines should probably be indented at the same level as the text in "Check version...", not at the same level as the "*"

[maresb]

Great work everyone!

I have been wondering, how does it work that we have this mixture between RST and Markdown? Is this enabled by a Sphinx plugin?

[OriolAbril]

I have been wondering, how does it work that we have this mixture between RST and Markdown? Is this enabled by a Sphinx plugin?

Yes, myst-parser is the one that makes this possible. https://sphinx-primer.readthedocs.io/en/latest/ has a quick overview of how sphinx is used for pymc docs in case you are interested

[twiecki]

Thanks so much @reshamas!