diff --git a/doc/devel/development_setup.rst b/doc/devel/development_setup.rst index 14a11add45b9..6404dc8a6e60 100644 --- a/doc/devel/development_setup.rst +++ b/doc/devel/development_setup.rst @@ -34,6 +34,22 @@ repository, you should first fork this repository by *clicking* the This creates a copy of the code under your account on the GitHub server. See `the GitHub documentation `__ for more details. +Decide whether to work locally or in GitHub Codespaces +====================================================== + +You can either work locally on your machine, or online in +`GitHub Codespaces `_, a cloud-based in-browser development +environment. If you are making a one-off, relatively simple change then +working in GitHub Codespaces can be a good option because most of the setting +up is done for you and you can skip the next few sections! If you are making +extensive or frequent contributions to Matplotlib then it is probably worth +taking the time to set up on your local machine: As well as having the +convenience of your local familiar tools, you will not need to worry about +Codespace's monthly usage limits. + +If you want to use Codespaces, skip to :ref:`development-codespaces`, +otherwise, continue with the next section. + Retrieve the latest version of the code ======================================= @@ -106,8 +122,8 @@ code, as described in :ref:`development-workflow`. .. _dev-environment: -Create a dedicated environment -============================== +Create a dedicated python environment +===================================== You should set up a dedicated environment to decouple your Matplotlib development from other Python and Matplotlib installations on your system. @@ -158,64 +174,69 @@ setup. Remember to activate the environment whenever you start working on Matplotlib! - .. tab-item:: :octicon:`codespaces` GitHub Codespaces - `GitHub Codespaces `_ is a cloud-based - in-browser development environment that comes with the appropriate setup to - contribute to Matplotlib. +Install external dependencies +============================= - #. Open codespaces on your fork by clicking on the green :octicon:`code` ``Code`` - button on the GitHub web interface and selecting the ``Codespaces`` tab. +Python dependencies were installed as part of :ref:`setting up the environment `. +Additionally, the following non-Python dependencies must also be installed locally: - #. Next, click on "Open codespaces on ". You will be - able to change branches later, so you can select the default - ``main`` branch. +.. rst-class:: checklist - #. 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``:: +* :ref:`c++ compiler` +* :ref:`external tools used by the documentation build ` - conda activate mpl-dev - Remember to activate the *mpl-dev* environment whenever you start working on - Matplotlib. +For a full list of dependencies, see :ref:`dependencies`. External dependencies do not +need to be installed when working in codespaces. - If you need to open a GUI window with Matplotlib output on Codespaces, our - configuration includes a `light-weight Fluxbox-based desktop - `_. - You can use it by connecting to this desktop via your web browser. To do this: +.. _development-codespaces: - #. 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. - #. In the browser that appears, click the Connect button and enter the desktop - password (``vscode`` by default). +:octicon:`codespaces` Create a GitHub Codespace +=============================================== - Check the `GitHub instructions - `_ - for more details on connecting to the desktop. +`GitHub Codespaces `_ is a cloud-based +in-browser development environment that comes with the appropriate setup to +contribute to Matplotlib. - 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." +#. Open codespaces on your fork by clicking on the green :octicon:`code` ``Code`` + button on the GitHub web interface and selecting the ``Codespaces`` tab. +#. Next, click on "Open codespaces on ". You will be + able to change branches later, so you can select the default + ``main`` branch. -Install external dependencies -============================= +#. 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``:: -Python dependencies were installed as part of :ref:`setting up the environment `. -Additionally, the following non-Python dependencies must also be installed locally: + conda activate mpl-dev -.. rst-class:: checklist +Remember to activate the *mpl-dev* environment whenever you start working on +Matplotlib. -* :ref:`c++ compiler` -* :ref:`external tools used by the documentation build ` +If you need to open a GUI window with Matplotlib output on Codespaces, our +configuration includes a `light-weight Fluxbox-based desktop +`_. +You can use it by connecting to this desktop via your web browser. To do this: +#. 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. +#. In the browser that appears, click the Connect button and enter the desktop + password (``vscode`` by default). -For a full list of dependencies, see :ref:`dependencies`. External dependencies do not -need to be installed when working in codespaces. +Check the `GitHub instructions +`_ +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." + +.. _`github-codespaces`: https://docs.github.com/codespaces .. _development-install: