Merge pull request #26201 from melissawm/add-codespaces-docs

story645 · web-flow · commit 0849036fd992 · 2023-08-15T09:51:20.000-04:00
DOC: Add documentation on codespaces usage
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
@@ -1,4 +1,3 @@
-
 {
   "hostRequirements": {
     "memory": "8gb",
@@ -13,6 +12,12 @@
   },
   "onCreateCommand": ".devcontainer/setup.sh",
   "postCreateCommand": "",
+  "forwardPorts": [6080],
+  "portsAttributes": {
+    "6080": {
+      "label": "desktop"
+    }
+  },
   "customizations": {
     "vscode": {
       "extensions": [
@@ -22,11 +27,12 @@
         "ms-vscode.live-server"
       ],
       "settings": {}
+    },
+    "codespaces": {
+      "openFiles": [
+        "README.md",
+        "doc/devel/codespaces.md"
+      ]
     }
-},
-"portsAttributes": {
-	"6080": {
-		"label": "desktop"
-	}
-}
+  }
 }
diff --git a/doc/devel/codespaces.md b/doc/devel/codespaces.md
@@ -0,0 +1,9 @@
+# Contributing to Matplotlib using GitHub codespaces
+
+* For a general overview of contributing to Matplotlib, see https://matplotlib.org/devdocs/devel/index.html
+
+* For instructions on how to submit Pull Requests using GitHub codespaces, see https://matplotlib.org/devdocs/devel/contribute.html#contributing-code
+
+* For instructions on running tests to verify your changes, see https://matplotlib.org/devdocs/devel/testing.html
+
+* For instructions on building the Matplotlib documentation, see https://matplotlib.org/devdocs/devel/document.html#documenting-matplotlib
diff --git a/doc/devel/contribute.rst b/doc/devel/contribute.rst
@@ -221,9 +221,13 @@ How to contribute
 
 The preferred way to contribute to Matplotlib is to fork the `main
 repository <https://github.com/matplotlib/matplotlib/>`__ on GitHub,
-then submit a "pull request" (PR).
+then submit a "pull request" (PR). You can do this by cloning a copy of the
+Maplotlib repository to your own computer, or alternatively using
+`GitHub Codespaces <https://docs.github.com/codespaces>`_, a cloud-based
+in-browser development environment that comes with the appropriated setup to
+contribute to Matplotlib.
 
-A brief overview is:
+A brief overview of the workflow is as follows.
 
 1. `Create an account <https://github.com/join>`_ on GitHub if you do not
    already have one.
@@ -232,35 +236,86 @@ A brief overview is:
    click on the 'Fork' button near the top of the page. This creates a copy of
    the code under your account on the GitHub server.
 
-3. Clone this copy to your local disk::
+.. tab-set::
 
-      git clone https://github.com/<YOUR GITHUB USERNAME>/matplotlib.git
+    .. tab-item:: Local development
 
-4. Enter the directory and install the local version of Matplotlib.
-   See :ref:`installing_for_devs` for instructions
+        3. Clone this copy to your local disk::
+
+             git clone https://github.com/<YOUR GITHUB USERNAME>/matplotlib.git
+
+    .. tab-item:: Using GitHub Codespaces
+
+        3. Check out the Matplotlib repository and activate your development
+           environment:
+
+           * Open codespaces on your fork by clicking on the green "Code" button
+             on the GitHub web interface and selecting the "Codespaces" tab.
+           * Next, click on "Open codespaces on <your branch name>". You will be
+             able to change branches later, so you can select the default
+             ``main`` branch.
+           * After the codespace is created, you will be taken to a new browser
+             tab where you can use the terminal to activate a pre-defined conda
+             environment called ``mpl-dev``::
+
+               conda activate mpl-dev
+
+
+
+4. Install the local version of Matplotlib with::
+
+     python -m pip install -e .
+
+   See :ref:`installing_for_devs` for detailed instructions.
 
 5. Create a branch to hold your changes::
 
-      git checkout -b my-feature origin/main
+     git checkout -b my-feature origin/main
 
    and start making changes. Never work in the ``main`` branch!
 
-6. Work on this copy, on your computer, using Git to do the version control.
-   When you're done editing e.g., ``lib/matplotlib/collections.py``, do::
+6. Work on this task using Git to do the version control. Codespaces persist for
+   some time (check the `documentation for details
+   <https://docs.github.com/codespaces/getting-started/the-codespace-lifecycle>`_)
+   and can be managed on https://github.com/codespaces. When you're done editing
+   e.g., ``lib/matplotlib/collections.py``, do::
 
-      git add lib/matplotlib/collections.py
-      git commit
+     git add lib/matplotlib/collections.py
+     git commit
 
-   to record your changes in Git, then push them to GitHub with::
+   to record your changes in Git, then push them to your GitHub fork with::
 
-      git push -u origin my-feature
+     git push -u origin my-feature
 
 Finally, go to the web page of your fork of the Matplotlib repo, and click
 'Pull request' to send your changes to the maintainers for review.
 
 For more detailed instructions on how to set up Matplotlib for development and
 best practices for contribution, see :ref:`installing_for_devs`.
 
+GitHub Codespaces workflows
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* If you need to open a GUI window with Matplotlib output on Codespaces, our
+  configuration includes a `light-weight Fluxbox-based desktop
+  <https://github.com/devcontainers/features/tree/main/src/desktop-lite>`_.
+  You can use it by connecting to this desktop via your web browser. To do this:
+
+  1. Press ``F1`` or ``Ctrl/Cmd+Shift+P`` and select
+     ``Ports: Focus on Ports View`` in the VSCode session to bring it into
+     focus. Open the ports view in your tool, select the ``noVNC`` port, and
+     click the Globe icon.
+  2. In the browser that appears, click the Connect button and enter the desktop
+     password (``vscode`` by default).
+
+  Check the `GitHub instructions
+  <https://github.com/devcontainers/features/tree/main/src/desktop-lite#connecting-to-the-desktop>`_
+  for more details on connecting to the desktop.
+
+* If you also built the documentation pages, you can view them using Codespaces.
+  Use the "Extensions" icon in the activity bar to install the "Live Server"
+  extension. Locate the ``doc/build/html`` folder in the Explorer, right click
+  the file you want to open and select "Open with Live Server."
 
 .. _contributing_documentation:
 
