8000 Merge pull request #19726 from meeseeksmachine/auto-backport-of-pr-19… · matplotlib/matplotlib@878db27 · GitHub
[go: up one dir, main page]
Skip to content

Commit 878db27

Browse files
QuLogicQuLogic
authored
Merge pull request #19726 from meeseeksmachine/auto-backport-of-pr-19505-on-v3.4.x
Backport PR #19505 on branch v3.4.x (Move some advanced documentation away from Installation Guide)
2 parents fae007b + 0057b42 commit 878db27

File tree

5 files changed

+180
-153
lines changed

5 files changed

+180
-153
lines changed

‎INSTALL.rst

Lines changed: 4 additions & 151 deletions
Original file line numberDiff line numberDiff line change
@@ -31,8 +31,8 @@ precompiled wheel for your OS and Python.
3131
TkAgg.
3232

3333
For support of other GUI frameworks, LaTeX rendering, saving
34-
animations and a larger selection of file formats, you need to
35-
install :ref:`additional dependencies <install_requirements>`.
34+
animations and a larger selection of file formats, you can
35+
install :ref:`optional_dependencies`.
3636

3737
Although not required, we suggest also installing ``IPython`` for
3838
interactive use. To easily install a complete Scientific Python
@@ -73,6 +73,8 @@ If you are interested in contributing to Matplotlib development,
7373
running the latest source code, or just like to build everything
7474
yourself, it is not difficult to build Matplotlib from source.
7575

76+
First you need to install the :ref:`dependencies`.
77+
7678
A C compiler is required. Typically, on Linux, you will need ``gcc``, which
7779
should be installed using your distribution's package manager; on macOS, you
7880
will need xcode_; on Windows, you will need Visual Studio 2015 or later.
@@ -135,149 +137,6 @@ file will be particularly useful to those packaging Matplotlib.
135137

136138
.. _setup.cfg: https://raw.githubusercontent.com/matplotlib/matplotlib/master/setup.cfg.template
137139

138-
.. _install_requirements:
139-
140-
Dependencies
141-
------------
142-
143-
Matplotlib will automatically install dependencies when you install with
144-
``pip``, so this section is mostly for your reference.
145-
146-
Matplotlib requires the following dependencies:
147-
148-
* `Python <https://www.python.org/downloads/>`_ (>= 3.7)
149-
* `NumPy <https://numpy.org>`_ (>= 1.16)
150-
* `setuptools <https://setuptools.readthedocs.io/en/latest/>`_
151-
* `cycler <https://matplotlib.org/cycler/>`_ (>= 0.10.0)
152-
* `dateutil <https://pypi.org/project/python-dateutil>`_ (>= 2.7)
153-
* `kiwisolver <https://github.com/nucleic/kiwi>`_ (>= 1.0.1)
154-
* `Pillow <https://pillow.readthedocs.io/en/latest/>`_ (>= 6.2)
155-
* `pyparsing <https://pypi.org/project/pyparsing/>`_ (>=2.2.1)
156-
157-
Optionally, you can also install a number of packages to enable better user
158-
interface toolkits. See :ref:`what-is-a-backend` for more details on the
159-
optional Matplotlib backends and the capabilities they provide.
160-
161-
* Tk_ (>= 8.3, != 8.6.0 or 8.6.1): for the Tk-based backends.
162-
* PyQt4_ (>= 4.6) or PySide_ (>= 1.0.3) [#]_: for the Qt4-based backends.
163-
* PyQt5_ or PySide2_: for the Qt5-based backends.
164-
* PyGObject_: for the GTK3-based backends [#]_.
165-
* wxPython_ (>= 4) [#]_: for the wx-based backends.
166-
* pycairo_ (>= 1.11.0) or cairocffi_ (>= 0.8): for the GTK3 and/or cairo-based
167-
backends.
168-
* Tornado_: for the WebAgg backend.
169-
170-
.. _Tk: https://docs.python.org/3/library/tk.html
171-
.. _PyQt4: https://pypi.org/project/PyQt4
172-
.. _PySide: https://pypi.org/project/PySide
173-
.. _PyQt5: https://pypi.org/project/PyQt5
174-
.. _PySide2: https://pypi.org/project/PySide2
175-
.. _PyGObject: https://pygobject.readthedocs.io/en/latest/
176-
.. _wxPython: https://www.wxpython.org/
177-
.. _pycairo: https://pycairo.readthedocs.io/en/latest/
178-
.. _cairocffi: https://cairocffi.readthedocs.io/en/latest/
179-
.. _Tornado: https://pypi.org/project/tornado
180-
181-
.. [#] PySide cannot be pip-installed on Linux (but can be conda-installed).
182-
.. [#] If using pip (and not conda), PyGObject must be built from source; see
183-
https://pygobject.readthedocs.io/en/latest/devguide/dev_environ.html.
184-
.. [#] If using pip (and not conda) on Linux, wxPython wheels must be manually
185-
downloaded from https://wxpython.org/pages/downloads/.
186-
187-
For better support of animation output format and image file formats, LaTeX,
188-
etc., you can install the following:
189-
190-
* `ffmpeg <https://www.ffmpeg.org/>`_: for saving movies.
191-
* `ImageMagick <https://www.imagemagick.org/script/index.php>`_: for saving
192-
animated gifs.
193-
* `LaTeX <https://www.latex-project.org/>`_ (with `cm-super
194-
<https://ctan.org/pkg/cm-super>`__ ) and `GhostScript (>=9.0)
195-
<https://ghostscript.com/download/>`_ : for rendering text with
196-
LaTeX.
197-
* `fontconfig <https://www.fontconfig.org>`_ (>= 2.7): for detection of system
198-
fonts on Linux.
199-
200-
FreeType and Qhull
201-
------------------
202-
203-
Matplotlib depends on FreeType_ (>= 2.3), a font rendering library, and on
204-
Qhull_ (>= 2020.2), a library for computing triangulations. By default,
205-
Matplotlib downloads and builds its own copies of FreeType (this is necessary
206-
to run the test suite, because different versions of FreeType rasterize
207-
characters differently) and of Qhull. As an exception, Matplotlib defaults to
208-
the system version of FreeType on AIX.
209-
210-
.. _FreeType: https://www.freetype.org/
211-
.. _Qhull: http://www.qhull.org/
212-
213-
To force Matplotlib to use a copy of FreeType or Qhull already installed in
214-
your system, create a :file:`setup.cfg` file with the following contents:
215-
216-
.. code-block:: cfg
217-
218-
[libs]
219-
system_freetype = true
220-
system_qhull = true
221-
222-
before running ``python -m pip install .``.
223-
224-
In this case, you need to install the FreeType and Qhull library and headers.
225-
This can be achieved using a package manager, e.g. for FreeType:
226-
227-
.. code-block:: sh
228-
229-
# Pick ONE of the following:
230-
sudo apt install libfreetype6-dev # Debian/Ubuntu
231-
sudo dnf install freetype-devel # Fedora
232-
brew install freetype # macOS with Homebrew
233-
conda install freetype # conda, any OS
234-
235-
(adapt accordingly for Qhull).
236-
237-
On Linux and macOS, it is also recommended to install pkg-config_, a helper
238-
tool for locating FreeType:
239-
240-
.. code-block:: sh
241-
242-
# Pick ONE of the following:
243-
sudo apt install pkg-config # Debian/Ubuntu
244-
sudo dnf install pkgconf # Fedora
245-
brew install pkg-config # macOS with Homebrew
246-
conda install pkg-config # conda
247-
# Or point the PKG_CONFIG environment variable to the path to pkg-config:
248-
export PKG_CONFIG=...
249-
250-
.. _pkg-config: https://www.freedesktop.org/wiki/Software/pkg-config/
251-
252-
If not using pkg-config (in particular on Windows), you may need to set the
253-
include path (to the library headers) and link path (to the libraries)
254-
explicitly, if they are not in standard locations. This can be done using
255-
standard environment variables -- on Linux and OSX:
256-
257-
.. code-block:: sh
258-
259-
export CFLAGS='-I/directory/containing/ft2build.h'
260-
export LDFLAGS='-L/directory/containing/libfreetype.so'
261-
262-
and on Windows:
263-
264-
.. code-block:: bat
265-
266-
set EED3 CL=/IC:\directory\containing\ft2build.h
267-
set LINK=/LIBPATH:C:\directory\containing\freetype.lib
268-
269-
.. note::
270-
271-
Matplotlib always uses its own copies of the following libraries:
272-
273-
- ``Agg``: the Anti-Grain Geometry C++ rendering engine;
274-
- ``ttconv``: a TrueType font utility.
275-
276-
If you go this route but need to reset and rebuild to change your settings,
277-
remember to clear your artifacts before re-building::
278-
279-
git clean -xfd
280-
281140
Building on Windows
282141
-------------------
283142

@@ -286,9 +145,3 @@ Visual Studio 2015 or later.
286145

287146
If you are building your own Matplotlib wheels (or sdists), note that any DLLs
288147
that you copy into the source tree will be packaged too.
289-
290-
Conda packages
291-
--------------
292-
293-
The conda packaging scripts for Matplotlib are available at
294-
https://github.com/conda-forge/matplotlib-feedstock.

‎doc/api/next_api_changes/deprecations/17662-TAC.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,8 @@ Increase minimum supported versions of Python and dependencies
22
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
33

44

5-
For Maptlotlib 3.4 the :ref:`minimum supported versions
6-
<install_requirements>` are being bumped
5+
For Maptlotlib 3.4 the :ref:`minimum supported versions <dependencies>`
6+
are being bumped
77

88
+------------+-----------------+---------------+
99
| Dependency | min in mpl3.3 | min in mpl3.4 |

‎doc/devel/dependencies.rst

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
.. _dependencies:
2+
3+
============
4+
Dependencies
5+
============
6+
7+
Mandatory dependencies
8+
======================
9+
10+
When installing through a package manager like ``pip`` or ``conda``, the
11+
mandatory dependencies are automatically installed. This list is mainly for
12+
reference.
13+
14+
* `Python <https://www.python.org/downloads/>`_ (>= 3.7)
15+
* `NumPy <https://numpy.org>`_ (>= 1.16)
16+
* `setuptools <https://setuptools.readthedocs.io/en/latest/>`_
17+
* `cycler <https://matplotlib.org/cycler/>`_ (>= 0.10.0)
18+
* `dateutil <https://pypi.org/project/python-dateutil>`_ (>= 2.7)
19+
* `kiwisolver <https://github.com/nucleic/kiwi>`_ (>= 1.0.1)
20+
* `Pillow <https://pillow.readthedocs.io/en/latest/>`_ (>= 6.2)
21+
* `pyparsing <https://pypi.org/project/pyparsing/>`_ (>=2.2.1)
22+
23+
24+
.. _optional_dependencies:
25+
26+
Optional dependencies
27+
=====================
28+
29+
The following packages and tools are not required but extend the capabilities
30+
of Matplotlib.
31+
32+
Backends
33+
--------
34+
35+
Matplotlib figures can be rendered to various user interfaces. See
36+
:ref:`what-is-a-backend` for more details on the optional Matplotlib backends
37+
and the capabilities they provide.
38+
39+
* Tk_ (>= 8.3, != 8.6.0 or 8.6.1) [#]_: for the Tk-based backends.
40+
* PyQt4_ (>= 4.6) or PySide_ (>= 1.0.3) [#]_: for the Qt4-based backends.
41+
* PyQt5_ or PySide2_: for the Qt5-based backends.
42+
* PyGObject_: for the GTK3-based backends [#]_.
43+
* wxPython_ (>= 4) [#]_: for the wx-based backends.
44+
* pycairo_ (>= 1.11.0) or cairocffi_ (>= 0.8): for the GTK3 and/or cairo-based
45+
backends.
46+
* Tornado_: for the WebAgg backend.
47+
48+
.. _Tk: https://docs.python.org/3/library/tk.html
49+
.. _PyQt4: https://pypi.org/project/PyQt4
50+
.. _PySide: https://pypi.org/project/PySide
51+
.. _PyQt5: https://pypi.org/project/PyQt5
52+
.. _PySide2: https://pypi.org/project/PySide2
53+
.. _PyGObject: https://pygobject.readthedocs.io/en/latest/
54+
.. _wxPython: https://www.wxpython.org/
55+
.. _pycairo: https://pycairo.readthedocs.io/en/latest/
56+
.. _cairocffi: https://cairocffi.readthedocs.io/en/latest/
57+
.. _Tornado: https://pypi.org/project/tornado
58+
59+
.. [#] Tk is part of most standard Python installations, but it's not part of
60+
Python itself and thus may not be present in rare cases.
61+
.. [#] PySide cannot be pip-installed on Linux (but can be conda-installed).
62+
.. [#] If using pip (and not conda), PyGObject must be built from source; see
63+
https://pygobject.readthedocs.io/en/latest/devguide/dev_environ.html.
64+
.. [#] If using pip (and not conda) on Linux, wxPython wheels must be manually
65+
downloaded from https://wxpython.org/pages/downloads/.
66+
67+
Animations
68+
----------
69+
70+
* `ffmpeg <https://www.ffmpeg.org/>`_: for saving movies.
71+
* `ImageMagick <https://www.imagemagick.org/script/index.php>`_: for saving
72+
animated gifs.
73+
74+
Font handling and rendering
75+
---------------------------
76+
77+
* `LaTeX <https://www.latex-project.org/>`_ (with `cm-super
78+
<https://ctan.org/pkg/cm-super>`__ ) and `GhostScript (>=9.0)
79+
<https://ghostscript.com/download/>`_ : for rendering text with LaTeX.
80+
* `fontconfig <https://www.fontconfig.org>`_ (>= 2.7): for detection of system
81+
fonts on Linux.
82+
83+
C libraries
84+
===========
85+
86+
Matplotlib brings its own copies of the following libraries:
87+
88+
- ``Agg``: the Anti-Grain Geometry C++ rendering engine
89+
- ``ttconv``: a TrueType font utility
90+
91+
Additionally, Matplotlib depends on:
92+
93+
- FreeType_ (>= 2.3): a font rendering library
94+
- QHull_ (>= 2020.2): a library for computing triangulations
95+
96+
.. _FreeType: https://www.freetype.org/
97+
.. _Qhull: http://www.qhull.org/
98+
99+
By default, Matplotlib downloads and builds its own copies of FreeType (this is
100+
necessary to run the test suite, because different versions of FreeType
101+
rasterize characters differently) and of Qhull. As an exception, Matplotlib
102+
defaults to the system version of FreeType on AIX.
103+
104+
To force Matplotlib to use a copy of FreeType or Qhull already installed in
105+
your system, create a :file:`setup.cfg` file with the following contents:
106+
107+
.. code-block:: cfg
108+
109+
[libs]
110+
system_freetype = true
111+
system_qhull = true
112+
113+
before running ``python -m pip install .``.
114+
115+
In this case, you need to install the FreeType and Qhull library and headers.
116+
This can be achieved using a package manager, e.g. for FreeType:
117+
118+
.. code-block:: sh
119+
120+
# Pick ONE of the following:
121+
sudo apt install libfreetype6-dev # Debian/Ubuntu
122+
sudo dnf install freetype-devel # Fedora
123+
brew install freetype # macOS with Homebrew
124+
conda install freetype # conda, any OS
125+
126+
(adapt accordingly for Qhull).
127+
128+
On Linux and macOS, it is also recommended to install pkg-config_, a helper
129+
tool for locating FreeType:
130+
131+
.. code-block:: sh
132+
133+
# Pick ONE of the following:
134+
sudo apt install pkg-config # Debian/Ubuntu
135+
sudo dnf install pkgconf # Fedora
136+
brew install pkg-config # macOS with Homebrew
137+
conda install pkg-config # conda
138+
# Or point the PKG_CONFIG environment variable to the path to pkg-config:
139+
export PKG_CONFIG=...
140+
141+
.. _pkg-config: https://www.freedesktop.org/wiki/Software/pkg-config/
142+
143+
If not using pkg-config (in particular on Windows), you may need to set the
144+
include path (to the library headers) and link path (to the libraries)
145+
explicitly, if they are not in standard locations. This can be done using
146+
standard environment variables -- on Linux and OSX:
147+
148+
.. code-block:: sh
149+
150+
export CFLAGS='-I/directory/containing/ft2build.h'
151+
export LDFLAGS='-L/directory/containing/libfreetype.so'
152+
153+
and on Windows:
154+
155+
.. code-block:: bat
156+
157+
set CL=/IC:\directory\containing\ft2build.h
158+
set LINK=/LIBPATH:C:\directory\containing\freetype.lib
159+
160+
If you go this route but need to reset and rebuild to change your settings,
161+
remember to clear your artifacts before re-building::
162+
163+
git clean -xfd

‎doc/devel/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,7 @@ process or how to fix something feel free to ask on `gitter
4040
gitwash/index.rst
4141
coding_guide.rst
4242
release_guide.rst
43+
dependencies.rst
4344
min_dep_policy.rst
4445
MEP/index
4546

‎doc/devel/release_guide.rst

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -382,3 +382,13 @@ In addition, announcements should be made on social networks (twitter
382382
via the ``@matplotlib`` account, any other via personal accounts).
383383
`NumFOCUS <https://numfocus.org/>`__ should be contacted for
384384
inclusion in their newsletter.
385+
386+
387+
Conda packages
388+
==============
389+
390+
The Matplotlib project itself does not release conda packages. In particular,
391+
the Matplotlib release manager is not responsible for conda packaging.
392+
393+
For information on the packaging of Matplotlib for conda-forge see
394+
https://github.com/conda-forge/matplotlib-feedstock.

0 commit comments

Comments
 (0)
0