Skip to content

Commit fa56972

Browse files
story645story645
committed
removed faq folder and added general faq link to user guide index,
moved install related troubleshooting/faq to install docs, consolidated information across install, install for dev, and dependencies
1 parent 0ac170b commit fa56972

13 files changed

Lines changed: 561 additions & 678 deletions

‎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.*']
126125

127126
exclude_patterns += skip_subdirs
128127

‎doc/devel/dependencies.rst‎

Lines changed: 12 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -240,17 +240,26 @@ 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. Typically, on Linux, you
244+
will need ``gcc``, which should be installed using your distribution's package
245+
manager; on macOS, you will need xcode; on Windows, you will need
246+
Visual Studio 2015 or later. Specifically:
244247

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.
248+
- `gcc 4.8.1 <https://gcc.gnu.org/projects/cxx-status.html#cxx11>`_ or higher. For gcc <6.5 you will need to set ``$CFLAGS=-std=c++11`` to enable C++11 support.
247249
`Installing GCC: Binaries <https://gcc.gnu.org/install/binaries.html>`_.
248250
- `clang 3.3 <https://clang.llvm.org/cxx_status.html>`_ or higher.
249251
`LLVM Download Page <https://releases.llvm.org/download.html>`_.
250252
- `Visual Studio 2015
251253
<https://docs.microsoft.com/en-us/cpp/overview/visual-cpp-language-conformance?view=msvc-140>`_
252254
(aka VS 14.0) or higher. A free version of Build Tools for Visual Studio is available for
253255
`download <https://visualstudio.microsoft.com/downloads/?q=build+tools>`_.
256+
- `xcode <https://developer.apple.com/xcode/>`_ for Apple platform development
257+
258+
For those using Visual Studio, make sure "Desktop development with C++" is
259+
selected, and that the latest MSVC, "C++ CMake tools for Windows," and a
260+
Windows SDK compatible with your version of Windows are selected and installed.
261+
They should be selected by default under the "Optional" subheading, but are
262+
required to build Matplotlib from source.
254263

255264

256265
.. _test-dependencies:

‎doc/devel/development_setup.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,12 @@ To set up Matplotlib for development follow these steps:
2121
.. contents::
2222
:local:
2323

24+
Install Dependencies
25+
====================
26+
Most Python dependencies will be installed when :ref:`setting up the environment <dev-environment>`
27+
but non-Python dependencies like C++ compilers, LaTeX, and other system applications
28+
must be installed separately. For a full list, see :ref:`dependencies`.
29+
2430
Fork the Matplotlib repository
2531
==============================
2632

‎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.inc.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/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

‎doc/missing-references.json‎

Lines changed: 348 additions & 385 deletions
Large diffs are not rendered by default.

doc/users/faq/howto_faq.rst renamed to doc/users/faq.rst

Lines changed: 83 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,12 @@
11
.. _howto-faq:
22

33
.. redirect-from:: /faq/howto_faq
4+
.. redirect-from:: /users/faq/howto_faq
5+
.. redirect-from:: /faq/index
46

5-
******
6-
How-to
7-
******
8-
9-
.. contents::
10-
:backlinks: none
11-
7+
==========================
8+
Frequently Asked Questions
9+
==========================
1210

1311
.. _how-to-too-many-ticks:
1412

@@ -199,14 +197,8 @@ different scales, you can often get ylabels that do not align
199197
vertically across the multiple subplots, which can be unattractive.
200198
By default, Matplotlib positions the x location of the ylabel so that
201199
it does not overlap any of the y ticks. You can override this default
202-
behavior by specifying the coordinates of the label. The example
203-
below shows the default behavior in the left subplots, and the manual
204-
setting in the right subplots.
205-
206-
.. figure:: ../../gallery/text_labels_and_annotations/images/sphx_glr_align_ylabels_001.png
207-
:target: ../../gallery/text_labels_and_annotations/align_ylabels.html
208-
:align: center
209-
:scale: 50
200+
behavior by specifying the coordinates of the label. To learn how, see
201+
:doc:`/gallery/text_labels_and_annotations/align_ylabels`
210202

211203
.. _howto-set-zorder:
212204

@@ -307,3 +299,79 @@ artists.
307299
You may be able to work on separate figures from separate threads. However,
308300
you must in that case use a *non-interactive backend* (typically Agg), because
309301
most GUI backends *require* being run from the main thread as well.
302+
303+
.. _reporting-problems:
304+
305+
Get help
306+
--------
307+
308+
There are a number of good resources for getting help with Matplotlib.
309+
There is a good chance your question has already been asked:
310+
311+
- The `mailing list archive
312+
<https://discourse.matplotlib.org/c/community/matplotlib-users/6>`_.
313+
314+
- `GitHub issues <https://github.com/matplotlib/matplotlib/issues>`_.
315+
316+
- Stackoverflow questions tagged `matplotlib
317+
<https://stackoverflow.com/questions/tagged/matplotlib>`_.
318+
319+
If you are unable to find an answer to your question through search, please
320+
provide the following information in your e-mail to the `mailing list
321+
<https://mail.python.org/mailman/listinfo/matplotlib-users>`_:
322+
323+
* Your operating system (Linux/Unix users: post the output of ``uname -a``).
324+
325+
* Matplotlib version::
326+
327+
python -c "import matplotlib; print(matplotlib.__version__)"
328+
329+
* Where you obtained Matplotlib (e.g., your Linux distribution's packages,
330+
GitHub, PyPI, or `Anaconda <https://www.anaconda.com/>`_).
331+
332+
* Any customizations to your ``matplotlibrc`` file (see
333+
:ref:`customizing`).
334+
335+
* If the problem is reproducible, please try to provide a *minimal*, standalone
336+
Python script that demonstrates the problem. This is *the* critical step.
337+
If you can't post a piece of code that we can run and reproduce your error,
338+
the chances of getting help are significantly diminished. Very often, the
339+
mere act of trying to minimize your code to the smallest bit that produces
340+
the error will help you find a bug in *your* code that is causing the
341+
problem.
342+
343+
* Matplotlib provides debugging information through the `logging` library, and
344+
a helper function to set the logging level: one can call ::
345+
346+
plt.set_loglevel("info") # or "debug" for more info
347+
348+
to obtain this debugging information.
349+
350+
Standard functions from the `logging` module are also applicable; e.g. one
351+
could call ``logging.basicConfig(level="DEBUG")`` even before importing
352+
Matplotlib (this is in particular necessary to get the logging info emitted
353+
during Matplotlib's import), or attach a custom handler to the "matplotlib"
354+
logger. This may be useful if you use a custom logging configuration.
355+
356+
If you compiled Matplotlib yourself, please also provide:
357+
358+
* any changes you have made to ``setup.py`` or ``setupext.py``.
359+
* the output of::
360+
361+
rm -rf build
362+
python setup.py build
363+
364+
The beginning of the build output contains lots of details about your
365+
platform that are useful for the Matplotlib developers to diagnose your
366+
problem.
367+
368+
* your compiler version -- e.g., ``gcc --version``.
369+
370+
Including this information in your first e-mail to the mailing list
371+
will save a lot of time.
372+
373+
You will likely get a faster response writing to the mailing list than
374+
filing a bug in the bug tracker. Most developers check the bug
375+
tracker only periodically. If your problem has been determined to be
376+
a bug and cannot be quickly solved, you may be asked to file a bug in
377+
the tracker so the issue doesn't get lost.

‎doc/users/faq/index.rst‎

Lines changed: 0 additions & 21 deletions
This file was deleted.

0 commit comments

Comments
 (0)