From 3866399dca7be58794f32381a7256c9c045aac4f Mon Sep 17 00:00:00 2001 From: Antony Lee Date: Tue, 17 Dec 2019 17:22:35 +0100 Subject: [PATCH] Be more opinionated for setting up a dev env. Tell users to always use a venv and always install in editable mode. If they know better, great. But let's not offer too many confusing options to newcomers. --- INSTALL.rst | 4 ++- doc/devel/contributing.rst | 70 ++++++++++++-------------------------- 2 files changed, 24 insertions(+), 50 deletions(-) diff --git a/INSTALL.rst b/INSTALL.rst index 88f5800166fd..b0ebe1d44f8f 100644 --- a/INSTALL.rst +++ b/INSTALL.rst @@ -159,7 +159,9 @@ FreeType and Qhull Matplotlib depends on `FreeType `_ (>= 2.3), a font rendering library, and on `Qhull `_ (>= 2015.2), a library for computing triangulations. By default, Matplotlib downloads and -builds its own copy of FreeType, and uses its own copy of Qhull. +builds its own copy of FreeType (this is necessary to run the test suite, +because different versions of FreeType rasterize characters differently), and +uses its own copy of Qhull. To force Matplotlib to use a copy of FreeType or Qhull already installed in your system, create a :file:`setup.cfg` file with the following contents: diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst index fc1d369a7bac..c35980142514 100644 --- a/doc/devel/contributing.rst +++ b/doc/devel/contributing.rst @@ -53,28 +53,8 @@ Thank you for your help in keeping bug reports complete, targeted and descriptiv Retrieving and installing the latest version of the code ======================================================== -When developing Matplotlib, sources must be downloaded, built, and installed into -a local environment on your machine. - -Follow the instructions detailed :ref:`here ` to set up your -environment to build Matplotlib from source. - -.. warning:: - - When working on Matplotlib sources, having multiple versions installed by - different methods into the same environment may not always work as expected. - -To work on Matplotlib sources, it is strongly recommended to set up an alternative -development environment, using the something like `virtual environments in python -`_, or a -`conda environment `_. - -If you choose to use an already existing environment, and not a clean virtual or -conda environment, uninstall the current version of Matplotlib in that environment -using the same method used to install it. - -If working on Matplotlib documentation only, the above steps are *not* absolutely -necessary. +When developing Matplotlib, sources must be downloaded, built, and installed +into a local environment on your machine. We use `Git `_ for version control and `GitHub `_ for hosting our main repository. @@ -88,19 +68,24 @@ and navigate to the :file:`matplotlib` directory. If you have the proper privile you can use ``git@`` instead of ``https://``, which works through the ssh protocol and might be easier to use if you are using 2-factor authentication. +Installing Matplotlib in developer mode +--------------------------------------- + +It is strongly recommended to set up a clean `virtual environment`_. Do not +use on a preexisting environment! -Building Matplotlib for image comparison tests ----------------------------------------------- +A new environment can be set up with :: -Matplotlib's test suite makes heavy use of image comparison tests, meaning -the result of a plot is compared against a known good result. Unfortunately, -different versions of FreeType produce differently formed characters, causing -these image comparisons to fail. To make them reproducible, Matplotlib is, by -default, built with a special local copy of FreeType. + python3 -mvenv /path/to/devel/env +and activated with one of the following:: -Installing Matplotlib in developer mode ---------------------------------------- + source /path/to/devel/env/bin/activate # Linux/macOS + /path/to/devel/env/Scripts/activate.bat # Windows cmd.exe + /path/to/devel/env/Scripts/Activate.ps1 # Windows PowerShell + +Whenever you plan to work on Matplotlib, remember to activate the development +environment in your shell! To install Matplotlib (and compile the C-extensions) run the following command from the top-level directory :: @@ -115,28 +100,15 @@ reflected the next time you import the library. If you change the C-extension source (which might happen if you change branches) you will need to run :: - python setup.py build + python setup.py build_ext --inplace or re-run ``python -mpip install -ve .``. -Alternatively, if you do :: - - python -mpip install -v . - -all of the files will be copied to the installation directory however, -you will have to rerun this command every time the source is changed. -Additionally you will need to copy :file:`setup.cfg.template` to -:file:`setup.cfg` and edit it to contain :: - - [test] - local_freetype = True - tests = True - -In either case you can then run the tests to check your work -environment is set up properly:: +You can then run the tests to check your work environment is set up properly:: - pytest + python -mpytest +.. _virtual environment: https://docs.python.org/3/library/venv.html .. _pytest: http://doc.pytest.org/en/latest/ .. _pep8: https://pep8.readthedocs.io/en/latest/ .. _Ghostscript: https://www.ghostscript.com/ @@ -260,7 +232,7 @@ tools: * Code with a good unittest coverage (at least 70%, better 100%), check with:: python -mpip install coverage - pytest --cov=matplotlib --showlocals -v + python -mpytest --cov=matplotlib --showlocals -v * No pyflakes warnings, check with::