Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 1b4b50b

Browse files
QuLogicQuLogic
authored
Merge pull request #26628 from story645/install-faq
DOC: move install related FAQ to install docs
2 parents 8c94cd2 + d5a54d1 commit 1b4b50b

14 files changed

+675
-652
lines changed

‎doc/conf.py‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -121,8 +121,7 @@ def _parse_skip_subdirs_file():
121121
]
122122

123123
exclude_patterns = [
124-
'api/prev_api_changes/api_changes_*/*'
125-
]
124+
'api/prev_api_changes/api_changes_*/*', '**/*inc.rst']
126125

127126
exclude_patterns += skip_subdirs
128127

‎doc/devel/dependencies.rst‎

Lines changed: 65 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@ The following packages and tools are not required but extend the capabilities
3838
of Matplotlib.
3939

4040
Backends
41-
~~~~~~~~
41+
^^^^^^^^
4242

4343
Matplotlib figures can be rendered to various user interfaces. See
4444
:ref:`what-is-a-backend` for more details on the optional Matplotlib backends
@@ -73,14 +73,14 @@ and the capabilities they provide.
7373
.. _ipykernel: https://pypi.org/project/ipykernel/
7474

7575
Animations
76-
~~~~~~~~~~
76+
^^^^^^^^^^
7777

7878
* `ffmpeg <https://www.ffmpeg.org/>`_: for saving movies.
7979
* `ImageMagick <https://www.imagemagick.org/script/index.php>`_: for saving
8080
animated gifs.
8181

8282
Font handling and rendering
83-
~~~~~~~~~~~~~~~~~~~~~~~~~~~
83+
^^^^^^^^^^^^^^^^^^^^^^^^^^^
8484

8585
* `LaTeX <https://www.latex-project.org/>`_ (with `cm-super
8686
<https://ctan.org/pkg/cm-super>`__ and `underscore
@@ -111,7 +111,7 @@ rasterize characters differently) and of Qhull. As an exception, Matplotlib
111111
defaults to the system version of FreeType on AIX.
112112

113113
Use system libraries
114-
~~~~~~~~~~~~~~~~~~~~
114+
^^^^^^^^^^^^^^^^^^^^
115115

116116
To force Matplotlib to use a copy of FreeType or Qhull already installed in
117117
your system, create a :file:`mplsetup.cfg` file with the following contents:
@@ -185,7 +185,7 @@ remember to clear your artifacts before re-building::
185185

186186

187187
Manual Download
188-
~~~~~~~~~~~~~~~
188+
^^^^^^^^^^^^^^^
189189

190190

191191
If the automatic download does not work (for example on air-gapped systems) it
@@ -240,17 +240,65 @@ Setup dependencies
240240
C++ compiler
241241
------------
242242

243-
Matplotlib requires a C++ compiler that supports C++11.
243+
Matplotlib requires a C++ compiler that supports C++11, and each platform has a
244+
development environment that must be installed before a compiler can be installed.
245+
246+
.. tab-set::
247+
248+
.. tab-item:: Linux
249+
250+
On some Linux systems, you can install a meta-build package. For example,
251+
on Ubuntu ``apt install build-essential``
252+
253+
Otherwise, use the system distribution's package manager to install
254+
:ref:`gcc <compiler-table>`.
255+
256+
.. tab-item:: macOS
257+
258+
Install `Xcode <https://developer.apple.com/xcode/>`_ for Apple platform development.
259+
260+
.. tab-item:: Windows
261+
262+
Install `Visual Studio Build Tools <https://visualstudio.microsoft.com/downloads/?q=build+tools>`_
263+
264+
Make sure "Desktop development with C++" is selected, and that the latest MSVC,
265+
"C++ CMake tools for Windows," and a Windows SDK compatible with your version
266+
of Windows are selected and installed. They should be selected by default under
267+
the "Optional" subheading, but are required to build Matplotlib from source.
268+
269+
Alternatively, you can install a Linux-like environment such as `CygWin <https://www.cygwin.com/>`_
270+
or `Windows Subsystem for Linux <https://learn.microsoft.com/en-us/windows/wsl/install>`_.
271+
272+
273+
We highly recommend that you install a compiler using your platform tool, i.e.,
274+
Xcode, VS Code or Linux package manager. Choose **one** compiler from this list:
275+
276+
.. _compiler-table:
277+
278+
.. list-table::
279+
:widths: 20 20 20 40
280+
:header-rows: 1
281+
282+
* - compiler
283+
- minimum version
284+
- platforms
285+
- notes
286+
* - GCC
287+
- **4.8.1**
288+
- Linux, macOS, Windows
289+
- `gcc 4.8.1 <https://gcc.gnu.org/projects/cxx-status.html#cxx11>`_,
290+
`GCC: Binaries <https://gcc.gnu.org/install/binaries.html>`_,
291+
292+
For gcc <6.5 you will need to set ``$CFLAGS=-std=c++11`` to enable C++11 support.
293+
* - Clang (LLVM)
294+
- **3.3**
295+
- Linux, macOS
296+
- `clang 3.3 <https://clang.llvm.org/cxx_status.html>`_, `LLVM <https://releases.llvm.org/download.html>`_
297+
* - MSVC++
298+
- **14.0**
299+
- Windows
300+
- `Visual Studio 2015 C++ <https://docs.microsoft.com/en-us/cpp/overview/visual-cpp-language-conformance?view=msvc-140>`_
244301

245-
- `gcc 4.8.1 <https://gcc.gnu.org/projects/cxx-status.html#cxx11>`_ or higher. For gcc <6.5 you will
246-
need to set ``$CFLAGS=-std=c++11`` to enable C++11 support.
247-
`Installing GCC: Binaries <https://gcc.gnu.org/install/binaries.html>`_.
248-
- `clang 3.3 <https://clang.llvm.org/cxx_status.html>`_ or higher.
249-
`LLVM Download Page <https://releases.llvm.org/download.html>`_.
250-
- `Visual Studio 2015
251-
<https://docs.microsoft.com/en-us/cpp/overview/visual-cpp-language-conformance?view=msvc-140>`_
252-
(aka VS 14.0) or higher. A free version of Build Tools for Visual Studio is available for
253-
`download <https://visualstudio.microsoft.com/downloads/?q=build+tools>`_.
254302

255303

256304
.. _test-dependencies:
@@ -286,8 +334,8 @@ testing the following will be used if they are installed.
286334
fonts for testing font fallback and non-western fonts
287335
- xarray_ used to test compatibility with xarray
288336

289-
If any of these dependencies are not discovered the tests that rely on them
290-
will be skipped by pytest.
337+
If any of these dependencies are not discovered, then the tests that rely on
338+
them will be skipped by pytest.
291339

292340
.. note::
293341

‎doc/devel/development_setup.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -148,6 +148,12 @@ The simplest way to do this is to use either Python's virtual environment
148148

149149
Remember to activate the environment whenever you start working on Matplotlib.
150150

151+
Install Dependencies
152+
====================
153+
Most Python dependencies will be installed when :ref:`setting up the environment <dev-environment>`
154+
but non-Python dependencies like C++ compilers, LaTeX, and other system applications
155+
must be installed separately. For a full list, see :ref:`dependencies`.
156+
151157
Install Matplotlib in editable mode
152158
===================================
153159

‎doc/devel/index.rst‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -78,6 +78,7 @@ Development environment
7878
.. grid:: 1 1 2 2
7979

8080
.. grid-item-card::
81+
:shadow: none
8182

8283
**Install**
8384
^^^
@@ -91,9 +92,11 @@ Development environment
9192
:maxdepth: 1
9293

9394
dependencies
95+
../users/installing/environment_variables_faq.rst
9496

9597

9698
.. grid-item-card::
99+
:shadow: none
97100

98101
**Workflow**
99102
^^^^
@@ -103,6 +106,10 @@ Development environment
103106

104107
development_workflow
105108

109+
.. toctree::
110+
:maxdepth: 1
111+
112+
troubleshooting.rst
106113

107114

108115
.. _contribution_guideline:
@@ -115,6 +122,7 @@ Policies and guidelines
115122
:gutter: 2
116123

117124
.. grid-item-card::
125+
:shadow: none
118126

119127
**Code**
120128
^^^
@@ -128,6 +136,7 @@ Policies and guidelines
128136
testing
129137

130138
.. grid-item-card::
139+
:shadow: none
131140

132141
**Documentation**
133142
^^^
@@ -139,6 +148,7 @@ Policies and guidelines
139148
style_guide
140149

141150
.. grid-item-card::
151+
:shadow: none
142152

143153
**Triage**
144154
^^^
@@ -148,6 +158,7 @@ Policies and guidelines
148158
| :ref:`triage_workflow`
149159
150160
.. grid-item-card::
161+
:shadow: none
151162

152163
**Maintenance**
153164
^^^

‎doc/devel/troubleshooting.rst‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
.. _troubleshooting-faq:
2+
3+
.. redirect-from:: /faq/troubleshooting_faq
4+
.. redirect-from:: /users/faq/troubleshooting_faq
5+
6+
===============
7+
Troubleshooting
8+
===============
9+
10+
For guidance on debugging an installation, see :ref:`installing-faq`.
11+
12+
13+
.. _git-trouble:
14+
15+
Problems with git
16+
=================
17+
18+
First, make sure you have a clean build and install (see :ref:`clean-install`),
19+
get the latest git update, install it and run a simple test script in debug
20+
mode::
21+
22+
rm -rf /path/to/site-packages/matplotlib*
23+
git clean -xfd
24+
git pull
25+
python -m pip install -v . > build.out
26+
python -c "from pylab import *; set_loglevel('debug'); plot(); show()" > run.out
27+
28+
and post :file:`build.out` and :file:`run.out` to the `matplotlib-devel
29+
<https://mail.python.org/mailman/listinfo/matplotlib-devel>`_
30+
mailing list (please do not post git problems to the `users list
31+
<https://mail.python.org/mailman/listinfo/matplotlib-users>`_).
32+
33+
Of course, you will want to clearly describe your problem, what you
34+
are expecting and what you are getting, but often a clean build and
35+
install will help. See also :ref:`reporting-problems`.
36+
37+
Unlink of file ``*/_c_internal_utils.cp311-win_amd64.pyd`` failed
38+
============================================================================
39+
40+
The DLL files may be loaded by multiple running instances of Matplotlib; therefore
41+
check that Matplotlib is not running in any other application before trying to
42+
unlink this file. Multiple versions of Matplotlib can be linked to the same DLL,
43+
for example a development version installed in a development conda environment
44+
and a stable version running in a Jupyter notebook. To resolve this error, fully
45+
close all running instances of Matplotlib.

‎doc/index.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,7 @@ Learn
5656
users/explain/quick_start
5757
User guide <users/index.rst>
5858
tutorials/index.rst
59-
users/faq/index.rst
59+
users/faq.rst
6060

6161
.. grid-item-card::
6262
:padding: 2

0 commit comments

Comments
 (0)