DOC: Add documentation on codespaces usage

[melissawm]

PR summary

This PR adds a skeleton for codespaces usage documentation. There are definitely improvements to be made but I have a couple of points:

• I've added a codespaces.md document instead of an .rst one because I feel like it will be possible to preview this markdown file automatically when the codespace is opened (see this topic and this comment (which is not generally possible with rst files)
• I have included a minimal set of instructions on the main building page without the desktop preview instructions because I feel that would be too much for new contributors, but I am open to any suggestions.

Addresses #26169

PR checklist

• "closes #0000" is in the body of the PR description to link the related issue
• new and changed code is tested
• Plotting related features are demonstrated in an example
• New Features and API Changes are noted with a directive and release note
• Documentation complies with general and docstring guidelines

[jklymak]

The tab on develop looks good. Why is the information then duplicated on a second page?

[story645]

I swear I like this more than my review makes it seem like I do :/

It's one of these things where I think it's great as a standalone guide but since we have all these other docs would prefer if it tied into them more.

[melissawm]

Because the codespaces.md file will hopefully be opened automatically when codespaces is fired up (which we can't do with rst files)

[jklymak]

Is that a usual thing for codespaces? Seems strange to pop open an editable file that is part of the repo.

Regardless id just have the markdown file have a link to the canonical instructions and not repeat info.

[tacaswell]

I think there is a vscode setting file we can drop to tell vscode we want to use the environment and it will auto-activate for us.

[melissawm]

I will investigate but this was not possible until recently because of the way the terminal is fired up when codespaces is first opened. They have been making a lot of updates lately so I'll verify.

[tacaswell]

I'm less worried about the duplicate text between the tabs. I think reading a unified top-to-bottom flow is nicer than reading it broken up.

Is there anything we can do about the navigation on the left? I am not sure what the right order is, but having "Contribute" below the MEP docs and near the bottom seems less than ideal. Looking at this whole section I think the bigger problem is less the repetition, but more the disjointedness as you read through the sections in the order on the left....

---

Regardless id just have the markdown file have a link to the canonical instructions and not repeat info.

If the goal is to make it easy for people to get started, I'm in favor of it being as obviously self documenting in-line as possible.

[marbled-toast]

I know the purpose of this document may not yet be determined. But, if this is ultimately going to be a beginner's guide for working in codespace, I suggest we remove the workflow for the preferred method throughout and just mention it with a link once. Afterward, only document for the codespaces workflow.

Then change Line 24 to:
A brief overview of the workflow with Codespaces follows.

[melissawm]

Here's a second take.

I made the codespaces.md file simpler to just link out to the actual contributing guide and reorganized the build instructions a little bit. I think I've addressed most comments but happy to have more feedback. Cheers!

Relevant artifact: https://output.circle-artifacts.com/output/job/b7e3320f-aab1-4533-8fd7-98b239eaf25f/artifacts/0/doc/build/html/devel/contribute.html#contributing-code

[story645]

Some style nits but generally I think this is awesome and addressed the concerns!

[melissawm]

Here's another take: https://output.circle-artifacts.com/output/job/279bd963-85a5-45e1-89a6-d8bc05a913d5/artifacts/0/doc/build/html/devel/contribute.html#contributing-code

The codespaces.md file is now just a list of links, and all the docs are in the Contribute page. I think this is much simpler and better!

@story645 the nested numbering is a bit tricky, let me know what you think of this version.

[story645]

@story645 the nested numbering is a bit tricky, let me know what you think of this version.

I see what you mean. Bullets or even spaces - so it's 3 short paragraphs- is also fine. I think it'd be better for the three steps in code spaces are clearly visually separated but I don't care much how.

And yeah I also like this version much much better.

[story645]

just posted an example of what I mean by visually distinguishable if the double listing takes up too much space.

[story645]

I really 😻 the sign-posting here

[QuLogic]

@meeseeksdev backport to v3.8.x
@meeseeksdev backport to v3.7.x

[lumberbot-app]

Owee, I'm MrMeeseeks, Look at me.

There seem to be a conflict, please backport manually. Here are approximate instructions:

1. Checkout backport branch and update it.

git checkout v3.7.x
git pull

2. Cherry pick the first parent branch of the this PR on top of the older branch:

git cherry-pick -x -m1 0849036fd992a2dd133a0cffc3f84f58ccf1840f

3. You will likely have some merge/cherry-pick conflict here, fix them and commit:

git commit -am 'Backport PR #26201: DOC: Add documentation on codespaces usage'

4. Push to a named branch:

git push YOURFORK v3.7.x:auto-backport-of-pr-26201-on-v3.7.x

5. Create a PR against branch v3.7.x, I would have named this PR:

"Backport PR #26201 on branch v3.7.x (DOC: Add documentation on codespaces usage)"

And apply the correct labels and milestones.

Congratulations — you did some good work! Hopefully your backport PR will be tested by the continuous integration and merged soon!

Remember to remove the Still Needs Manual Backport label once the PR gets merged.

If these instructions are inaccurate, feel free to suggest an improvement.

[QuLogic]

I don't feel like doing that backport close to 3.8 release.