Skip to content

DOC: Add documentation on codespaces usage #26201

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Aug 15, 2023
Merged

DOC: Add documentation on codespaces usage #26201

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
00eb561
DOC: Add documentation on codespaces usage
melissawm Jun 26, 2023
a28db86
MAINT: Fix port forwarding for desktop on codespaces
melissawm Jun 26, 2023
9a089fb
Addressing reviewer's comments
melissawm Aug 11, 2023
97c999c
Fix Codespaces admonition title
melissawm Aug 11, 2023
8c3a9c0
Fix headings, wording and numbered list in codespaces docs
melissawm Aug 11, 2023
34c7e52
Add bullet points to codespaces instructions
melissawm Aug 14, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 13 additions & 7 deletions .devcontainer/devcontainer.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,3 @@

{
"hostRequirements": {
"memory": "8gb",
Expand All @@ -13,6 +12,12 @@
},
"onCreateCommand": ".devcontainer/setup.sh",
"postCreateCommand": "",
"forwardPorts": [6080],
"portsAttributes": {
"6080": {
"label": "desktop"
}
},
"customizations": {
"vscode": {
"extensions": [
Expand All @@ -22,11 +27,12 @@
"ms-vscode.live-server"
],
"settings": {}
},
"codespaces": {
"openFiles": [
"README.md",
"doc/devel/codespaces.md"
]
}
},
"portsAttributes": {
"6080": {
"label": "desktop"
}
}
}
}
9 changes: 9 additions & 0 deletions doc/devel/codespaces.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
# Contributing to Matplotlib using GitHub codespaces
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I really 😻 the sign-posting here


* 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
81 changes: 68 additions & 13 deletions doc/devel/contribute.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -222,9 +222,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.
Expand All @@ -233,35 +237,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:

Expand Down