Doc updates #9291

anntzer · 2017-10-06T06:31:51Z

PR Summary

Document using pip for installation throughout (closes Document that python setup.py develop add the symlink to easy-install.pth #7422).
manylinux wheels are now available and a reasonable approach too.
Move the git install faq below the non-git install faq.
Most GUI toolkits are now pip and/or conda-installable on recent Pythons (GObject is the main outlier), update the venv docs as such. In other cases, https://github.com/stuaxo/vext can be used to punch a hole from the venvs to system-site-packages in a controlled manner.
Dedent the bullet list at http://matplotlib.org/devdocs/faq/troubleshooting_faq.html#getting-help, which currently appears within a blockquote.
Suggest using python -c "from pylab import *; plot(); show()" --verbose-helpful for a minimal error message, which avoids needing to create a separate script file.

PR Checklist

Has Pytest style unit tests
Code is PEP 8 compliant
New features are documented, with examples if plot related
Documentation is sphinx and numpydoc compliant
Added an entry to doc/users/next_whats_new/ if major new feature (follow instructions in README.rst there)
Documented in doc/api/api_changes.rst if API changed in a backward-incompatible way

The situation is much better: most GUI toolkits are now pip-installable.

tacaswell · 2017-10-06T06:42:49Z

doc/faq/installing_faq.rst

@@ -267,14 +178,14 @@ retry the install.  If that does not work, then check
 Installing via OSX mpkg installer package
 -----------------------------------------

-matplotlib also has a disk image (``.dmg``) installer, which contains a
-typical Installer.app package to install matplotlib.  You should use binary
+Matplotlib also has a disk image (``.dmg``) installer, which contains a


This is no longer true, we only do wheels on mac now. Can you remove all references to dmg files?

Can you just edit accordingly? I have close to no idea how things work on OSX, so I can cargo it but I'd rather not.

I also have no idea how macs work, but I do know we do not build a dmg file.

just killed the section

tacaswell · 2017-10-06T06:45:59Z

doc/faq/troubleshooting_faq.rst


-    rm -rf build
    rm -rf /path/to/site-packages/matplotlib*


This can be replaced by pip unistall matplotlib

I intentionally left it to cover the case of "seriously broken install" but not sure it's worth it -- let me know what you think.

That is a compelling position, including a reference to pip uninstall matplotlib someplace would be good though.

jklymak · 2017-10-06T17:55:57Z

doc/faq/installing_faq.rst

+If you want to be able to follow the development branch as it changes
+just replace the last step with::
+
+   pip install -e .


One gotcha that I've run into is pip not being installed in the conda environment I'm in, so it uses the default pip, and installs the development version over the released version in my main conda environment. Not sure where environments fit into this document, but something that could be discussed.

I updated the thing to use python -mpip throughout, which should make sure pip always works from (and thus, in) the local environment.
I also think that conda now installs pip by default in all envs? (but it's even if it doesn't it's not a problem as long as you use python -mpip).

Mainly dedent the bullet list, so that it does not appear as a rst blockquote.

Mostly moving away from python3.4 in the examples.

tacaswell · 2017-10-07T02:00:16Z

I am 👍 on what @anntzer wrote, but added a few commits so I don't want to merge this. Anyone (including @anntzer ) should merge this if it is a net improvement to the docs.

jklymak · 2017-10-07T02:07:18Z

doc/faq/installing_faq.rst

-your system to install matplotlib. This will guarantee that everything
-that is needed for matplotlib will be installed as well.
+To install Matplotlib at the system-level we recommend that you use your 
+distribution's package manager to install Matplotlib.  This will guarantee 


Suggest drop: "...to install Matplotlib"

jklymak · 2017-10-07T02:08:23Z

doc/faq/installing_faq.rst

-comes with at least a basic build system. Follow the :ref:`instructions
-<install-from-git>` found above for how to build and install matplotlib.
+If, for some reason, you can not use the package manager, you may use the
+manylinux wheels available on PyPI::


OK, when I read this I thought that manylinux was a typo. Put in quotes?

https://github.com/pypa/manylinux They never use quotes, I do not think we want to deviate from their notation.

It's a bit jargon-esque but I'd prefer leaving it as it is.

Not a big deal, but how about "...you may use the wheels available from manylinux, available on PyPI"

use the manylinux-tagged wheels, available on PyPI OK?

Sounds good!

Upon further throught I just dropped the "manylinux", as they are the only kind of linux wheels on pypi anyways, and either the reader knows what it means in which case it's obvious the wheels should be manylinux-tagged, or the reader doesn't and that doesn't help him at all.

jklymak · 2017-10-07T06:40:22Z

doc/faq/installing_faq.rst

-If, for some reason, you can not use the package manager, Linux usually
-comes with at least a basic build system. Follow the :ref:`instructions
-<install-from-git>` found above for how to build and install matplotlib.
+If, for some reason, you can notuse the package manager, you may use the wheels


Notuse -> not use

removed the wrong space :) fixed

DOC: Install instruction updates

tacaswell · 2017-10-07T22:43:50Z

backported as 22c088e

Update venv faq.

3b52f44

The situation is much better: most GUI toolkits are now pip-installable.

tacaswell added this to the 2.1.0-docs milestone Oct 6, 2017

tacaswell reviewed Oct 6, 2017

View reviewed changes

anntzer force-pushed the doc-updates branch 3 times, most recently from 4fe9110 to 7490eb5 Compare October 6, 2017 07:06

dstansby added the Documentation label Oct 6, 2017

jklymak reviewed Oct 6, 2017

View reviewed changes

anntzer added 2 commits October 6, 2017 11:46

Update installation faq.

296befb

Update troubleshooting faq.

10f78c4

Mainly dedent the bullet list, so that it does not appear as a rst blockquote.

anntzer force-pushed the doc-updates branch from 7490eb5 to b3a9b36 Compare October 6, 2017 18:47

Fully switch from setup.py install to pip.

ca0114f

anntzer force-pushed the doc-updates branch from b3a9b36 to ca0114f Compare October 6, 2017 18:50

tacaswell added 2 commits October 6, 2017 21:46

DOC: tweak package manager istall wording

87960f8

DOC: tweak OSX install faq

3ae1336

Mostly moving away from python3.4 in the examples.

tacaswell approved these changes Oct 7, 2017

View reviewed changes

jklymak reviewed Oct 7, 2017

View reviewed changes

Tweak wording in install faq.

5562bf0

anntzer force-pushed the doc-updates branch from 9691e03 to 5562bf0 Compare October 7, 2017 06:42

tacaswell merged commit cc7de70 into matplotlib:master Oct 7, 2017

anntzer deleted the doc-updates branch October 7, 2017 22:41

tacaswell added a commit that referenced this pull request Oct 7, 2017

Merge pull request #9291 from anntzer/doc-updates

22c088e

DOC: Install instruction updates

jklymak mentioned this pull request Oct 12, 2017

DOC: fill out dev docs #9378

Merged

QuLogic mentioned this pull request Feb 9, 2018

Change setup.py install recommendation to pip install . #5428

Closed

timhoffm mentioned this pull request Nov 17, 2019

Dev docs update #15617

Merged

11 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Doc updates #9291

Doc updates #9291

anntzer commented Oct 6, 2017

tacaswell Oct 6, 2017

anntzer Oct 6, 2017

tacaswell Oct 6, 2017

anntzer Oct 6, 2017

tacaswell Oct 6, 2017

anntzer Oct 6, 2017

tacaswell Oct 6, 2017

jklymak Oct 6, 2017

anntzer Oct 6, 2017

tacaswell commented Oct 7, 2017

jklymak Oct 7, 2017

jklymak Oct 7, 2017

tacaswell Oct 7, 2017

anntzer Oct 7, 2017

jklymak Oct 7, 2017

anntzer Oct 7, 2017

jklymak Oct 7, 2017

anntzer Oct 7, 2017

jklymak Oct 7, 2017

anntzer Oct 7, 2017

tacaswell commented Oct 7, 2017

Doc updates #9291

Doc updates #9291

Conversation

anntzer commented Oct 6, 2017

PR Summary

PR Checklist

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tacaswell commented Oct 7, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tacaswell commented Oct 7, 2017