From a280b73fede8bbcbacb9a63ac855d9daa84eb597 Mon Sep 17 00:00:00 2001 From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com> Date: Thu, 11 Feb 2021 23:51:14 +0100 Subject: [PATCH 1/2] Move docs on dependencies and conda packages from installation guide to devdocs --- INSTALL.rst | 148 ------------------------------------ doc/devel/dependencies.rst | 143 ++++++++++++++++++++++++++++++++++ doc/devel/index.rst | 1 + doc/devel/release_guide.rst | 11 +++ 4 files changed, 155 insertions(+), 148 deletions(-) create mode 100644 doc/devel/dependencies.rst diff --git a/INSTALL.rst b/INSTALL.rst index 4716296ac504..641969b3e845 100644 --- a/INSTALL.rst +++ b/INSTALL.rst @@ -135,148 +135,6 @@ file will be particularly useful to those packaging Matplotlib. .. _setup.cfg: https://raw.githubusercontent.com/matplotlib/matplotlib/master/setup.cfg.template -.. _install_requirements: - -Dependencies ------------- - -Matplotlib will automatically install dependencies when you install with -``pip``, so this section is mostly for your reference. - -Matplotlib requires the following dependencies: - -* `Python `_ (>= 3.7) -* `NumPy `_ (>= 1.16) -* `setuptools `_ -* `cycler `_ (>= 0.10.0) -* `dateutil `_ (>= 2.7) -* `kiwisolver `_ (>= 1.0.1) -* `Pillow `_ (>= 6.2) -* `pyparsing `_ (>=2.2.1) - -Optionally, you can also install a number of packages to enable better user -interface toolkits. See :ref:`what-is-a-backend` for more details on the -optional Matplotlib backends and the capabilities they provide. - -* Tk_ (>= 8.3, != 8.6.0 or 8.6.1): for the Tk-based backends. -* PyQt4_ (>= 4.6) or PySide_ (>= 1.0.3) [#]_: for the Qt4-based backends. -* PyQt5_ or PySide2_: for the Qt5-based backends. -* PyGObject_: for the GTK3-based backends [#]_. -* wxPython_ (>= 4) [#]_: for the wx-based backends. -* pycairo_ (>= 1.11.0) or cairocffi_ (>= 0.8): for the GTK3 and/or cairo-based - backends. -* Tornado_: for the WebAgg backend. - -.. _Tk: https://docs.python.org/3/library/tk.html -.. _PyQt4: https://pypi.org/project/PyQt4 -.. _PySide: https://pypi.org/project/PySide -.. _PyQt5: https://pypi.org/project/PyQt5 -.. _PySide2: https://pypi.org/project/PySide2 -.. _PyGObject: https://pygobject.readthedocs.io/en/latest/ -.. _wxPython: https://www.wxpython.org/ -.. _pycairo: https://pycairo.readthedocs.io/en/latest/ -.. _cairocffi: https://cairocffi.readthedocs.io/en/latest/ -.. _Tornado: https://pypi.org/project/tornado - -.. [#] PySide cannot be pip-installed on Linux (but can be conda-installed). -.. [#] If using pip (and not conda), PyGObject must be built from source; see - https://pygobject.readthedocs.io/en/latest/devguide/dev_environ.html. -.. [#] If using pip (and not conda) on Linux, wxPython wheels must be manually - downloaded from https://wxpython.org/pages/downloads/. - -For better support of animation output format and image file formats, LaTeX, -etc., you can install the following: - -* `ffmpeg `_: for saving movies. -* `ImageMagick `_: for saving - animated gifs. -* `LaTeX `_ (with `cm-super - `__ ) and `GhostScript (>=9.0) - `_ : for rendering text with - LaTeX. -* `fontconfig `_ (>= 2.7): for detection of system - fonts on Linux. - -FreeType and Qhull ------------------- - -Matplotlib depends on FreeType_ (>= 2.3), a font rendering library, and on -Qhull_ (>= 2020.2), a library for computing triangulations. By default, -Matplotlib downloads and builds its own copies of FreeType (this is necessary -to run the test suite, because different versions of FreeType rasterize -characters differently) and of Qhull. As an exception, Matplotlib defaults to -the system version of FreeType on AIX. - -.. _FreeType: https://www.freetype.org/ -.. _Qhull: http://www.qhull.org/ - -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: - -.. code-block:: cfg - - [libs] - system_freetype = true - system_qhull = true - -before running ``python -m pip install .``. - -In this case, you need to install the FreeType and Qhull library and headers. -This can be achieved using a package manager, e.g. for FreeType: - -.. code-block:: sh - - # Pick ONE of the following: - sudo apt install libfreetype6-dev # Debian/Ubuntu - sudo dnf install freetype-devel # Fedora - brew install freetype # macOS with Homebrew - conda install freetype # conda, any OS - -(adapt accordingly for Qhull). - -On Linux and macOS, it is also recommended to install pkg-config_, a helper -tool for locating FreeType: - -.. code-block:: sh - - # Pick ONE of the following: - sudo apt install pkg-config # Debian/Ubuntu - sudo dnf install pkgconf # Fedora - brew install pkg-config # macOS with Homebrew - conda install pkg-config # conda - # Or point the PKG_CONFIG environment variable to the path to pkg-config: - export PKG_CONFIG=... - -.. _pkg-config: https://www.freedesktop.org/wiki/Software/pkg-config/ - -If not using pkg-config (in particular on Windows), you may need to set the -include path (to the library headers) and link path (to the libraries) -explicitly, if they are not in standard locations. This can be done using -standard environment variables -- on Linux and OSX: - -.. code-block:: sh - - export CFLAGS='-I/directory/containing/ft2build.h' - export LDFLAGS='-L/directory/containing/libfreetype.so' - -and on Windows: - -.. code-block:: bat - - set CL=/IC:\directory\containing\ft2build.h - set LINK=/LIBPATH:C:\directory\containing\freetype.lib - -.. note:: - - Matplotlib always uses its own copies of the following libraries: - - - ``Agg``: the Anti-Grain Geometry C++ rendering engine; - - ``ttconv``: a TrueType font utility. - -If you go this route but need to reset and rebuild to change your settings, -remember to clear your artifacts before re-building:: - - git clean -xfd Building on Windows ------------------- @@ -286,9 +144,3 @@ Visual Studio 2015 or later. If you are building your own Matplotlib wheels (or sdists), note that any DLLs that you copy into the source tree will be packaged too. - -Conda packages --------------- - -The conda packaging scripts for Matplotlib are available at -https://github.com/conda-forge/matplotlib-feedstock. diff --git a/doc/devel/dependencies.rst b/doc/devel/dependencies.rst new file mode 100644 index 000000000000..bb539504aa30 --- /dev/null +++ b/doc/devel/dependencies.rst @@ -0,0 +1,143 @@ +.. _install_requirements: + +============ +Dependencies +============ + +Matplotlib will automatically install dependencies when you install with +``pip``, so this section is mostly for your reference. + +Matplotlib requires the following dependencies: + +* `Python `_ (>= 3.7) +* `NumPy `_ (>= 1.16) +* `setuptools `_ +* `cycler `_ (>= 0.10.0) +* `dateutil `_ (>= 2.7) +* `kiwisolver `_ (>= 1.0.1) +* `Pillow `_ (>= 6.2) +* `pyparsing `_ (>=2.2.1) + +Optionally, you can also install a number of packages to enable better user +interface toolkits. See :ref:`what-is-a-backend` for more details on the +optional Matplotlib backends and the capabilities they provide. + +* Tk_ (>= 8.3, != 8.6.0 or 8.6.1): for the Tk-based backends. +* PyQt4_ (>= 4.6) or PySide_ (>= 1.0.3) [#]_: for the Qt4-based backends. +* PyQt5_ or PySide2_: for the Qt5-based backends. +* PyGObject_: for the GTK3-based backends [#]_. +* wxPython_ (>= 4) [#]_: for the wx-based backends. +* pycairo_ (>= 1.11.0) or cairocffi_ (>= 0.8): for the GTK3 and/or cairo-based + backends. +* Tornado_: for the WebAgg backend. + +.. _Tk: https://docs.python.org/3/library/tk.html +.. _PyQt4: https://pypi.org/project/PyQt4 +.. _PySide: https://pypi.org/project/PySide +.. _PyQt5: https://pypi.org/project/PyQt5 +.. _PySide2: https://pypi.org/project/PySide2 +.. _PyGObject: https://pygobject.readthedocs.io/en/latest/ +.. _wxPython: https://www.wxpython.org/ +.. _pycairo: https://pycairo.readthedocs.io/en/latest/ +.. _cairocffi: https://cairocffi.readthedocs.io/en/latest/ +.. _Tornado: https://pypi.org/project/tornado + +.. [#] PySide cannot be pip-installed on Linux (but can be conda-installed). +.. [#] If using pip (and not conda), PyGObject must be built from source; see + https://pygobject.readthedocs.io/en/latest/devguide/dev_environ.html. +.. [#] If using pip (and not conda) on Linux, wxPython wheels must be manually + downloaded from https://wxpython.org/pages/downloads/. + +For better support of animation output format and image file formats, LaTeX, +etc., you can install the following: + +* `ffmpeg `_: for saving movies. +* `ImageMagick `_: for saving + animated gifs. +* `LaTeX `_ (with `cm-super + `__ ) and `GhostScript (>=9.0) + `_ : for rendering text with + LaTeX. +* `fontconfig `_ (>= 2.7): for detection of system + fonts on Linux. + +FreeType and Qhull +------------------ + +Matplotlib depends on FreeType_ (>= 2.3), a font rendering library, and on +Qhull_ (>= 2020.2), a library for computing triangulations. By default, +Matplotlib downloads and builds its own copies of FreeType (this is necessary +to run the test suite, because different versions of FreeType rasterize +characters differently) and of Qhull. As an exception, Matplotlib defaults to +the system version of FreeType on AIX. + +.. _FreeType: https://www.freetype.org/ +.. _Qhull: http://www.qhull.org/ + +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: + +.. code-block:: cfg + + [libs] + system_freetype = true + system_qhull = true + +before running ``python -m pip install .``. + +In this case, you need to install the FreeType and Qhull library and headers. +This can be achieved using a package manager, e.g. for FreeType: + +.. code-block:: sh + + # Pick ONE of the following: + sudo apt install libfreetype6-dev # Debian/Ubuntu + sudo dnf install freetype-devel # Fedora + brew install freetype # macOS with Homebrew + conda install freetype # conda, any OS + +(adapt accordingly for Qhull). + +On Linux and macOS, it is also recommended to install pkg-config_, a helper +tool for locating FreeType: + +.. code-block:: sh + + # Pick ONE of the following: + sudo apt install pkg-config # Debian/Ubuntu + sudo dnf install pkgconf # Fedora + brew install pkg-config # macOS with Homebrew + conda install pkg-config # conda + # Or point the PKG_CONFIG environment variable to the path to pkg-config: + export PKG_CONFIG=... + +.. _pkg-config: https://www.freedesktop.org/wiki/Software/pkg-config/ + +If not using pkg-config (in particular on Windows), you may need to set the +include path (to the library headers) and link path (to the libraries) +explicitly, if they are not in standard locations. This can be done using +standard environment variables -- on Linux and OSX: + +.. code-block:: sh + + export CFLAGS='-I/directory/containing/ft2build.h' + export LDFLAGS='-L/directory/containing/libfreetype.so' + +and on Windows: + +.. code-block:: bat + + set CL=/IC:\directory\containing\ft2build.h + set LINK=/LIBPATH:C:\directory\containing\freetype.lib + +.. note:: + + Matplotlib always uses its own copies of the following libraries: + + - ``Agg``: the Anti-Grain Geometry C++ rendering engine; + - ``ttconv``: a TrueType font utility. + +If you go this route but need to reset and rebuild to change your settings, +remember to clear your artifacts before re-building:: + + git clean -xfd diff --git a/doc/devel/index.rst b/doc/devel/index.rst index 53f08af76122..c2c140173227 100644 --- a/doc/devel/index.rst +++ b/doc/devel/index.rst @@ -40,6 +40,7 @@ process or how to fix something feel free to ask on `gitter gitwash/index.rst coding_guide.rst release_guide.rst + dependencies.rst min_dep_policy.rst MEP/index diff --git a/doc/devel/release_guide.rst b/doc/devel/release_guide.rst index e8e55c57a151..cdcbc4ed3c5e 100644 --- a/doc/devel/release_guide.rst +++ b/doc/devel/release_guide.rst @@ -382,3 +382,14 @@ In addition, announcements should be made on social networks (twitter via the ``@matplotlib`` account, any other via personal accounts). `NumFOCUS `__ should be contacted for inclusion in their newsletter. + + +Conda packages +============== + +The conda packaging scripts for Matplotlib are hosted at +https://github.com/conda-forge/matplotlib-feedstock. + +This is for information only. The conda packages are not released by the +Matplotlib project but by third parties. In particular, the Matplotlib release +manager is not responsible for conda packaging. From 00112faddef9733da0eb46ff3d4ce200e36cdc9b Mon Sep 17 00:00:00 2001 From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com> Date: Fri, 12 Feb 2021 00:38:11 +0100 Subject: [PATCH 2/2] Rewording and minor restructuring of dependencies docs --- INSTALL.rst | 7 +- .../deprecations/17662-TAC.rst | 4 +- doc/devel/dependencies.rst | 86 ++++++++++++------- doc/devel/release_guide.rst | 9 +- 4 files changed, 63 insertions(+), 43 deletions(-) diff --git a/INSTALL.rst b/INSTALL.rst index 641969b3e845..fea85b3e8af6 100644 --- a/INSTALL.rst +++ b/INSTALL.rst @@ -31,8 +31,8 @@ precompiled wheel for your OS and Python. TkAgg. For support of other GUI frameworks, LaTeX rendering, saving - animations and a larger selection of file formats, you need to - install :ref:`additional dependencies `. + animations and a larger selection of file formats, you can + install :ref:`optional_dependencies`. Although not required, we suggest also installing ``IPython`` for interactive use. To easily install a complete Scientific Python @@ -73,6 +73,8 @@ If you are interested in contributing to Matplotlib development, running the latest source code, or just like to build everything yourself, it is not difficult to build Matplotlib from source. +First you need to install the :ref:`dependencies`. + A C compiler is required. Typically, on Linux, you will need ``gcc``, which should be installed using your distribution's package manager; on macOS, you will need xcode_; on Windows, you will need Visual Studio 2015 or later. @@ -135,7 +137,6 @@ file will be particularly useful to those packaging Matplotlib. .. _setup.cfg: https://raw.githubusercontent.com/matplotlib/matplotlib/master/setup.cfg.template - Building on Windows ------------------- diff --git a/doc/api/next_api_changes/deprecations/17662-TAC.rst b/doc/api/next_api_changes/deprecations/17662-TAC.rst index 61791346679a..7fdfce7977cb 100644 --- a/doc/api/next_api_changes/deprecations/17662-TAC.rst +++ b/doc/api/next_api_changes/deprecations/17662-TAC.rst @@ -2,8 +2,8 @@ Increase minimum supported versions of Python and dependencies ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -For Maptlotlib 3.4 the :ref:`minimum supported versions -` are being bumped +For Maptlotlib 3.4 the :ref:`minimum supported versions ` +are being bumped +------------+-----------------+---------------+ | Dependency | min in mpl3.3 | min in mpl3.4 | diff --git a/doc/devel/dependencies.rst b/doc/devel/dependencies.rst index bb539504aa30..c28283517005 100644 --- a/doc/devel/dependencies.rst +++ b/doc/devel/dependencies.rst @@ -1,13 +1,15 @@ -.. _install_requirements: +.. _dependencies: ============ Dependencies ============ -Matplotlib will automatically install dependencies when you install with -``pip``, so this section is mostly for your reference. +Mandatory dependencies +====================== -Matplotlib requires the following dependencies: +When installing through a package manager like ``pip`` or ``conda``, the +mandatory dependencies are automatically installed. This list is mainly for +reference. * `Python `_ (>= 3.7) * `NumPy `_ (>= 1.16) @@ -18,11 +20,23 @@ Matplotlib requires the following dependencies: * `Pillow `_ (>= 6.2) * `pyparsing `_ (>=2.2.1) -Optionally, you can also install a number of packages to enable better user -interface toolkits. See :ref:`what-is-a-backend` for more details on the -optional Matplotlib backends and the capabilities they provide. -* Tk_ (>= 8.3, != 8.6.0 or 8.6.1): for the Tk-based backends. +.. _optional_dependencies: + +Optional dependencies +===================== + +The following packages and tools are not required but extend the capabilities +of Matplotlib. + +Backends +-------- + +Matplotlib figures can be rendered to various user interfaces. See +:ref:`what-is-a-backend` for more details on the optional Matplotlib backends +and the capabilities they provide. + +* Tk_ (>= 8.3, != 8.6.0 or 8.6.1) [#]_: for the Tk-based backends. * PyQt4_ (>= 4.6) or PySide_ (>= 1.0.3) [#]_: for the Qt4-based backends. * PyQt5_ or PySide2_: for the Qt5-based backends. * PyGObject_: for the GTK3-based backends [#]_. @@ -42,38 +56,51 @@ optional Matplotlib backends and the capabilities they provide. .. _cairocffi: https://cairocffi.readthedocs.io/en/latest/ .. _Tornado: https://pypi.org/project/tornado +.. [#] Tk is part of most standard Python installations, but it's not part of + Python itself and thus may not be present in rare cases. .. [#] PySide cannot be pip-installed on Linux (but can be conda-installed). .. [#] If using pip (and not conda), PyGObject must be built from source; see https://pygobject.readthedocs.io/en/latest/devguide/dev_environ.html. .. [#] If using pip (and not conda) on Linux, wxPython wheels must be manually downloaded from https://wxpython.org/pages/downloads/. -For better support of animation output format and image file formats, LaTeX, -etc., you can install the following: +Animations +---------- * `ffmpeg `_: for saving movies. * `ImageMagick `_: for saving animated gifs. + +Font handling and rendering +--------------------------- + * `LaTeX `_ (with `cm-super `__ ) and `GhostScript (>=9.0) - `_ : for rendering text with - LaTeX. + `_ : for rendering text with LaTeX. * `fontconfig `_ (>= 2.7): for detection of system fonts on Linux. -FreeType and Qhull ------------------- +C libraries +=========== -Matplotlib depends on FreeType_ (>= 2.3), a font rendering library, and on -Qhull_ (>= 2020.2), a library for computing triangulations. By default, -Matplotlib downloads and builds its own copies of FreeType (this is necessary -to run the test suite, because different versions of FreeType rasterize -characters differently) and of Qhull. As an exception, Matplotlib defaults to -the system version of FreeType on AIX. +Matplotlib brings its own copies of the following libraries: + +- ``Agg``: the Anti-Grain Geometry C++ rendering engine +- ``ttconv``: a TrueType font utility + +Additionally, Matplotlib depends on: + +- FreeType_ (>= 2.3): a font rendering library +- QHull_ (>= 2020.2): a library for computing triangulations .. _FreeType: https://www.freetype.org/ .. _Qhull: http://www.qhull.org/ +By default, Matplotlib downloads and builds its own copies of FreeType (this is +necessary to run the test suite, because different versions of FreeType +rasterize characters differently) and of Qhull. As an exception, Matplotlib +defaults to the system version of FreeType on AIX. + 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: @@ -92,9 +119,9 @@ This can be achieved using a package manager, e.g. for FreeType: # Pick ONE of the following: sudo apt install libfreetype6-dev # Debian/Ubuntu - sudo dnf install freetype-devel # Fedora - brew install freetype # macOS with Homebrew - conda install freetype # conda, any OS + sudo dnf install freetype-devel # Fedora + brew install freetype # macOS with Homebrew + conda install freetype # conda, any OS (adapt accordingly for Qhull). @@ -105,9 +132,9 @@ tool for locating FreeType: # Pick ONE of the following: sudo apt install pkg-config # Debian/Ubuntu - sudo dnf install pkgconf # Fedora - brew install pkg-config # macOS with Homebrew - conda install pkg-config # conda + sudo dnf install pkgconf # Fedora + brew install pkg-config # macOS with Homebrew + conda install pkg-config # conda # Or point the PKG_CONFIG environment variable to the path to pkg-config: export PKG_CONFIG=... @@ -130,13 +157,6 @@ and on Windows: set CL=/IC:\directory\containing\ft2build.h set LINK=/LIBPATH:C:\directory\containing\freetype.lib -.. note:: - - Matplotlib always uses its own copies of the following libraries: - - - ``Agg``: the Anti-Grain Geometry C++ rendering engine; - - ``ttconv``: a TrueType font utility. - If you go this route but need to reset and rebuild to change your settings, remember to clear your artifacts before re-building:: diff --git a/doc/devel/release_guide.rst b/doc/devel/release_guide.rst index cdcbc4ed3c5e..92d6473d09c4 100644 --- a/doc/devel/release_guide.rst +++ b/doc/devel/release_guide.rst @@ -387,9 +387,8 @@ inclusion in their newsletter. Conda packages ============== -The conda packaging scripts for Matplotlib are hosted at -https://github.com/conda-forge/matplotlib-feedstock. +The Matplotlib project itself does not release conda packages. In particular, +the Matplotlib release manager is not responsible for conda packaging. -This is for information only. The conda packages are not released by the -Matplotlib project but by third parties. In particular, the Matplotlib release -manager is not responsible for conda packaging. +For information on the packaging of Matplotlib for conda-forge see +https://github.com/conda-forge/matplotlib-feedstock.