DOC: Add documentation on codespaces usage by melissawm · Pull Request #26201 · matplotlib/matplotlib · GitHub

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

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

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.

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

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.

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.

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.

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.

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.

* Reducing duplication by linking out to contribute guide * Rewording instructions and adding notes on codespaces-specific workflows

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

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

Co-authored-by: marbled-toast <69227427+marbled-toast@users.noreply.github.com> Co-authored-by: hannah <story645@gmail.com>

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 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.

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

I really 😻 the sign-posting here

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

Owee, I'm MrMeeseeks, Look at me.

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

Checkout backport branch and update it.

git checkout v3.7.x
git pull

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

git cherry-pick -x -m1 0849036fd992a2dd133a0cffc3f84f58ccf1840f

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'

Push to a named branch:

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

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.

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

…201-on-v3.8.x Backport PR #26201 on branch v3.8.x (DOC: Add documentation on codespaces usage)

melissawm added 2 commits June 26, 2023 19:54

DOC: Add documentation on codespaces usage

00eb561

MAINT: Fix port forwarding for desktop on codespaces

a28db86

melissawm added the Documentation label Jun 27, 2023

story645 reviewed Jun 27, 2023

View reviewed changes

Comment thread doc/devel/contribute.rst Outdated

Comment thread doc/devel/contribute.rst Outdated

Comment thread doc/devel/contribute.rst Outdated

tacaswell reviewed Jun 28, 2023

View reviewed changes

marbled-toast reviewed Jul 16, 2023

View reviewed changes

Addressing reviewer's comments

9a089fb

* Reducing duplication by linking out to contribute guide * Rewording instructions and adding notes on codespaces-specific workflows

Fix Codespaces admonition title

97c999c

story645 approved these changes Aug 11, 2023

View reviewed changes

Comment thread doc/devel/contribute.rst Outdated

Comment thread doc/devel/contribute.rst Outdated

Comment thread doc/devel/contribute.rst Outdated

Comment thread doc/devel/contribute.rst Outdated

Comment thread doc/devel/contribute.rst Outdated

Fix headings, wording and numbered list in codespaces docs

8c3a9c0

Co-authored-by: marbled-toast <69227427+marbled-toast@users.noreply.github.com> Co-authored-by: hannah <story645@gmail.com>

melissawm force-pushed the add-codespaces-docs branch from 8f9a882 to 8c3a9c0 Compare August 14, 2023 15:59

story645 reviewed Aug 14, 2023

View reviewed changes

Add bullet points to codespaces instructions

34c7e52

story645 approved these changes Aug 14, 2023

View reviewed changes

story645 merged commit 0849036 into matplotlib:main Aug 15, 2023

story645 modified the milestones: v3.8.0, v3.7-doc Aug 15, 2023

QuLogic modified the milestones: v3.7-doc, v3.7.3 Aug 18, 2023

meeseeksmachine mentioned this pull request Aug 18, 2023

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

Merged

lumberbot-app Bot added the Still Needs Manual Backport label Aug 18, 2023

meeseeksmachine pushed a commit to meeseeksmachine/matplotlib that referenced this pull request Aug 18, 2023

Backport PR matplotlib#26201 : DOC: Add documentation on codespaces usage

58ce652

QuLogic modified the milestones: v3.7.3, v3.8.0 Aug 18, 2023

QuLogic removed the Still Needs Manual Backport label Aug 18, 2023

ksunden added a commit that referenced this pull request Aug 18, 2023

Merge pull request #26546 from meeseeksmachine/auto-backport-of-pr-26…

92e771d

…201-on-v3.8.x Backport PR #26201 on branch v3.8.x (DOC: Add documentation on codespaces usage)

story645 mentioned this pull request Aug 22, 2023

[DOC]: codespace link in contribute index #26573

Merged

ksunden mentioned this pull request Sep 15, 2023

merge up v3.8.0 #26785

Merged

5 tasks

story645 mentioned this pull request Sep 29, 2023

Improve git setup instructions #20102

Closed

+                 `mpl-dev`:
+                 ```
+                 conda activate mpl-dev

+              in-browser development environment, that comes with the appropriated setup to
+              contribute to Matplotlib).
+              A brief overview of the workflows is as follows.

		@@ -0,0 +1,9 @@
		# Contributing to Matplotlib using GitHub codespaces

DOC: Add documentation on codespaces usage by melissawm · Pull Request #26201 · matplotlib/matplotlib · GitHub

Repository navigation

DOC: Add documentation on codespaces usage - #26201

DOC: Add documentation on codespaces usage#26201story645 merged 6 commits intomatplotlib:mainmatplotlib/matplotlib:mainfrom melissawm:add-codespaces-docsmelissawm/matplotlib:add-codespaces-docsCopy head branch name to clipboard

Conversation

melissawm commented Jun 27, 2023

PR summary

PR checklist

Uh oh!

jklymak commented Jun 27, 2023

Uh oh!

story645 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

melissawm commented Jun 27, 2023

Uh oh!

jklymak commented Jun 27, 2023

Uh oh!

tacaswell Jun 28, 2023

Choose a reason for hiding this comment

Uh oh!

melissawm Aug 11, 2023

Choose a reason for hiding this comment

Uh oh!

tacaswell commented Jun 28, 2023

Uh oh!

marbled-toast Jul 16, 2023

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

melissawm commented Aug 11, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

story645 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

melissawm commented Aug 14, 2023

Uh oh!

story645 commented Aug 14, 2023

Uh oh!

story645 left a comment

Choose a reason for hiding this comment

Uh oh!

story645 Aug 14, 2023

Choose a reason for hiding this comment

Uh oh!

Uh oh!

QuLogic commented Aug 18, 2023

Uh oh!

lumberbot-app Bot commented Aug 18, 2023

Uh oh!

QuLogic commented Aug 18, 2023

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

DOC: Add documentation on codespaces usage#26201
story645 merged 6 commits into
matplotlib:mainfrom
melissawm:add-codespaces-docs

melissawm commented Aug 11, 2023 •
edited
Loading