From 1fec2ae0bffb5af39ce073afa6a330a1f3bb1b60 Mon Sep 17 00:00:00 2001 From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com> Date: Sat, 2 Jan 2021 03:05:14 +0100 Subject: [PATCH] Collect information for setting up a development environment --- doc/devel/contributing.rst | 75 ------------------ doc/devel/development_setup.rst | 135 ++++++++++++++++++++++++++++++++ doc/devel/documenting_mpl.rst | 54 ++----------- doc/devel/index.rst | 1 + doc/devel/testing.rst | 25 ++---- 5 files changed, 147 insertions(+), 143 deletions(-) create mode 100644 doc/devel/development_setup.rst diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst index 45f958001b69..850be2ac6138 100644 --- a/doc/devel/contributing.rst +++ b/doc/devel/contributing.rst @@ -74,81 +74,6 @@ Matplotlib is an open source project with limited resources, we encourage users to then also :ref:`participate in the implementation `. -.. _installing_for_devs: - -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. - -We use `Git `_ for version control and -`GitHub `_ for hosting our main repository. - -You can check out the latest sources with the command (see -:ref:`set-up-fork` for more details):: - - git clone https://github.com/matplotlib/matplotlib.git - -and navigate to the :file:`matplotlib` directory. If you have the proper privileges, -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! - -A new environment can be set up with :: - - python3 -mvenv - -and activated with one of the following:: - - source /bin/activate # Linux/macOS - \Scripts\activate.bat # Windows cmd.exe - \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 :: - - python -mpip install -ve . - -This installs Matplotlib in 'editable/develop mode', i.e., builds -everything and places the correct link entries in the install -directory so that python will be able to import Matplotlib from the -source directory. Thus, any changes to the ``*.py`` files will be -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_ext --inplace - -or re-run ``python -mpip install -ve .``. - -You can then run the tests to check your work environment is set up properly:: - - 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/ -.. _Inkscape: https://inkscape.org/ - -.. note:: - - **Additional dependencies for testing**: pytest_ (version 3.6 or later), - Ghostscript_, Inkscape_ - -.. seealso:: - - * :ref:`testing` - .. _contributing-code: Contributing code diff --git a/doc/devel/development_setup.rst b/doc/devel/development_setup.rst new file mode 100644 index 000000000000..62184c2e66b7 --- /dev/null +++ b/doc/devel/development_setup.rst @@ -0,0 +1,135 @@ +.. _installing_for_devs: + +===================================== +Setting up Matplotlib for development +===================================== + +.. _dev-environment: + +Creating a dedicated environment +================================ +You should set up a dedicated environment to decouple your Matplotlib +development from other Python and Matplotlib installations on your system. +Here we use python's virtual environment `venv`_, but you may also use others +such as conda. + +.. _venv: https://docs.python.org/3/library/venv.html + +A new environment can be set up with :: + + python -m venv + +and activated with one of the following:: + + source /bin/activate # Linux/macOS + \Scripts\activate.bat # Windows cmd.exe + \Scripts\Activate.ps1 # Windows PowerShell + +Whenever you plan to work on Matplotlib, remember to activate the development +environment in your shell. + +Retrieving the latest version of the code +========================================= + +Matplotlib is hosted at https://github.com/matplotlib/matplotlib.git. + +You can retrieve the latest sources with the command (see +:ref:`set-up-fork` for more details):: + + git clone https://github.com/matplotlib/matplotlib.git + +This will place the sources in a directory :file:`matplotlib` below your +current working directory. + +If you have the proper privileges, 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 editable mode +====================================== +Install Matplotlib in editable mode from the :file:`matplotlib` directory +using the command :: + + python -m pip install -ve . + +The 'editable/develop mode', builds everything and places links in your Python +environment so that Python will be able to import Matplotlib from your +development source directory. This allows you to import your modified version +of Matplotlib without re-installing after every change. Note that this is only +true for ``*.py`` files. If you change the C-extension source (which might +also happen if you change branches) you will have to re-run +``python -mpip install -ve .`` + +.. _test-dependencies: + +Additional dependencies for testing +=================================== +This section lists the additional software required for +:ref:`running the tests `. + +Required: + +- pytest_ (>=3.6) +- Ghostscript_ (>= 9.0, to render PDF files) +- Inkscape_ (to render SVG files) + +Optional: + +- pytest-cov_ (>=2.3.1) to collect coverage information +- pytest-flake8_ to test coding standards using flake8_ +- pytest-timeout_ to limit runtime in case of stuck tests +- pytest-xdist_ to run tests in parallel + +.. _pytest: http://doc.pytest.org/en/latest/ +.. _Ghostscript: https://www.ghostscript.com/ +.. _Inkscape: https://inkscape.org +.. _pytest-cov: https://pytest-cov.readthedocs.io/en/latest/ +.. _pytest-flake8: https://pypi.org/project/pytest-flake8/ +.. _pytest-xdist: https://pypi.org/project/pytest-xdist/ +.. _pytest-timeout: https://pypi.org/project/pytest-timeout/ +.. _flake8: https://pypi.org/project/flake8/ + + +.. _doc-dependencies: + +Additional dependencies for building documentation +================================================== + +Python packages +--------------- +The additional Python packages required to build the +:ref:`documentation ` are listed in +:file:`doc-requirements.txt` and can be installed using :: + + pip install -r requirements/doc/doc-requirements.txt + +The content of :file:`doc-requirements.txt` is also shown below: + + .. include:: ../../requirements/doc/doc-requirements.txt + :literal: + +Additional external dependencies +-------------------------------- +Required: + +* a minimal working LaTeX distribution +* `Graphviz `_ +* the LaTeX packages *cm-super* and *dvipng*. If your OS bundles ``TexLive``, + then often the "complete" version of the installer will automatically include + these packages (e.g. "texlive-full" or "texlive-all"). + +Optional, but recommended: + +* `Inkscape `_ +* `optipng `_ +* the font "Humor Sans" (aka the "XKCD" font), or the free alternative + `Comic Neue `_. +* the font "Times New Roman" + +.. note:: + + The documentation will not build without LaTeX and Graphviz. These are not + Python packages and must be installed separately. The documentation can be + built without Inkscape and optipng, but the build process will raise various + warnings. If the build process warns that you are missing fonts, make sure + your LaTeX distribution bundles cm-super or install it separately. diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst index 1afe4ec9ff66..20e0168f83b8 100644 --- a/doc/devel/documenting_mpl.rst +++ b/doc/devel/documenting_mpl.rst @@ -14,7 +14,6 @@ Writing documentation Getting started =============== - General file structure ---------------------- @@ -51,55 +50,12 @@ Setting up the doc build ------------------------ The documentation for Matplotlib is generated from reStructuredText (ReST_) -using the Sphinx_ documentation generation tool. To build the documentation -you will need to - -1. set up an appropriate Python environment -2. install additional external dependencies - -Setting up a dedicated Python environment -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -* create a clean virtual environment with no existing Matplotlib installation -* install the Python packages required for Matplotlib -* install the additional Python packages required to build the documentation. - They are listed in :file:`doc-requirements.txt`, which is shown below: - - .. include:: ../../requirements/doc/doc-requirements.txt - :literal: - -.. note:: - - If you've already set up an - :ref:`environment for Matplotlib development `, you - can reuse that and skip the first two steps. - -Install additional external dependencies -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Required: - -* a minimal working LaTeX distribution -* `Graphviz `_ -* the LaTeX packages *cm-super* and *dvipng*. If your OS bundles ``TexLive``, - then often the "complete" version of the installer will automatically include - these packages (e.g. "texlive-full" or "texlive-all"). - -Optional, but recommended: - -* `Inkscape `_ -* `optipng `_ -* the font "Humor Sans" (aka the "XKCD" font), or the free alternative - `Comic Neue `_. -* the font "Times New Roman" - -.. note:: +using the Sphinx_ documentation generation tool. - The documentation will not build without LaTeX and Graphviz. These are not - Python packages and must be installed separately. The documentation can be - built without Inkscape and optipng, but the build process will raise various - warnings. If the build process warns that you are missing fonts, make sure - your LaTeX distribution bundles cm-super or install it separately. +To build the documentation you will need to +:ref:`set up Matplotlib for development `. Note in +particular the :ref:`additional dependencies ` required to +build the documentation. Building the docs ----------------- diff --git a/doc/devel/index.rst b/doc/devel/index.rst index a172c6e53c67..0c94454e6285 100644 --- a/doc/devel/index.rst +++ b/doc/devel/index.rst @@ -18,6 +18,7 @@ The Matplotlib Developers' Guide contributing.rst triage.rst + development_setup.rst testing.rst documenting_mpl.rst add_new_projection.rst diff --git a/doc/devel/testing.rst b/doc/devel/testing.rst index 008ad2cb934a..0449ff7fd251 100644 --- a/doc/devel/testing.rst +++ b/doc/devel/testing.rst @@ -9,33 +9,20 @@ Matplotlib's testing infrastructure depends on pytest_. The tests are in infrastructure are in :mod:`matplotlib.testing`. .. _pytest: http://doc.pytest.org/en/latest/ -.. _Ghostscript: https://www.ghostscript.com/ -.. _Inkscape: https://inkscape.org -.. _pytest-cov: https://pytest-cov.readthedocs.io/en/latest/ .. _pytest-flake8: https://pypi.org/project/pytest-flake8/ .. _pytest-xdist: https://pypi.org/project/pytest-xdist/ .. _pytest-timeout: https://pypi.org/project/pytest-timeout/ .. _flake8: https://pypi.org/project/flake8/ -Requirements ------------- - -Install the latest version of Matplotlib as documented in -:ref:`installing_for_devs`. - -The following software is required to run the tests: -- pytest_ (>=3.6) -- Ghostscript_ (>= 9.0, to render PDF files) -- Inkscape_ (to render SVG files) +.. _testing_requirements: -Optionally you can install: - -- pytest-cov_ (>=2.3.1) to collect coverage information -- pytest-flake8_ to test coding standards using flake8_ -- pytest-timeout_ to limit runtime in case of stuck tests -- pytest-xdist_ to run tests in parallel +Requirements +------------ +To run the tests you will need to +:ref:`set up Matplotlib for development `. Note in +particular the :ref:`additional dependencies ` for testing. Running the tests -----------------