8000 DOC: improve dev install docs by story645 · Pull Request #29705 · matplotlib/matplotlib · GitHub
[go: up one dir, main page]
Skip to content

DOC: improve dev install docs #29705

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 1 commit into from
Mar 5, 2025
Merged

DOC: improve dev install docs #29705

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
7 changes: 4 additions & 3 deletions doc/_static/mpl.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -195,15 +195,16 @@ div.wide-table table th.stub {
}

/* section-toc is a custom class that removes the page title from a toctree listing
* and shifts the resulting list left
* Example usage:
*
* .. rst-class:: section-toc
* .. toctree::
*
*/
.section-toc.toctree-wrapper .toctree-l1>a{
.section-toc.toctree-wrapper .toctree-l1>a{
display: none;
}
.section-toc.toctree-wrapper li>ul{
padding-inline-start:0;
.section-toc.toctree-wrapper .toctree-l1>ul{
padding-left: 0;
}
64 changes: 44 additions & 20 deletions doc/devel/development_setup.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,24 +34,31 @@ 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 <https://docs.github.com/get-started/quickstart/fork-a-repo>`__ for more details.

Decide whether to work locally or in GitHub Codespaces
======================================================
Set up development environment
==============================

You can either work locally on your machine, or online in
`GitHub Codespaces <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.
environment.


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

:codespaces: 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 want to use Codespaces, skip to :ref:`development-codespaces`,
otherwise, continue with the next section.

Retrieve the latest version of the code
=======================================
Create local environment
------------------------

Get most recent code
^^^^^^^^^^^^^^^^^^^^

Now that your fork of the repository lives under your GitHub username, you can
retrieve the most recent version of the source code with one of the following
Expand Down Expand Up @@ -122,8 +129,9 @@ code, as described in :ref:`development-workflow`.

.. _dev-environment:

Create a dedicated python environment
=====================================
Create a dedicated environment
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You should set up a dedicated environment to decouple your Matplotlib
development from other Python and Matplotlib installations on your system.

Expand All @@ -142,11 +150,27 @@ setup.

python -m venv <file folder location>

and activate it with one of the following ::
and activate it with one of the following :

.. tab-set::

.. tab-item:: Linux and macOS

.. code-block:: bash

source <file folder location>/bin/activate # Linux/macOS

.. tab-item:: Windows cmd.exe

.. code-block:: bat

<file folder location>\Scripts\activate.bat

.. tab-item:: Windows PowerShell

.. code-block:: ps1con

source <file folder location>/bin/activate # Linux/macOS
<file folder location>\Scripts\activate.bat # Windows cmd.exe
<file folder location>\Scripts\Activate.ps1 # Windows PowerShell
<file folder location>\Scripts\Activate.ps1

On some systems, you may need to type ``python3`` instead of ``python``.
For a discussion of the technical reasons, see `PEP-394 <https://peps.python.org/pep-0394>`_.
Expand Down Expand Up @@ -176,7 +200,7 @@ setup.


Install external dependencies
=============================
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Python dependencies were installed as part of :ref:`setting up the environment <dev-environment>`.
Additionally, the following non-Python dependencies must also be installed locally:
Expand All @@ -192,8 +216,8 @@ need to be installed when working in codespaces.

.. _development-codespaces:

:octicon:`codespaces` Create a GitHub Codespace
===============================================
Create GitHub Codespace :octicon:`codespaces`
---------------------------------------------

`GitHub Codespaces <github-codespaces_>`_ is a cloud-based
in-browser development environment that comes with the appropriate setup to
Expand Down
4 changes: 2 additions & 2 deletions doc/devel/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -160,9 +160,9 @@ and managing a development environment and workflow:

**Install**
^^^

.. rst-class:: section-toc
.. toctree::
:maxdepth: 2
:maxdepth: 4

development_setup

Expand Down
Loading
0