DOC refactored installation instruction #8240

NelleV · 2017-03-08T19:43:17Z

This is a small refactoring of the installation instructions. I've mostly merged three files together and did some markup updates.

We now have only on README file, common to the three plateforms. The INSTALL file contains installation instructions for all plateform. It probably needs a bit of love.

Don't hesitate to edit the document directly.

phobson

I think this a good change. It'll be nice to have this all in one spot.

phobson · 2017-03-09T05:12:43Z

INSTALL

@@ -325,7 +325,32 @@ can get the libpng and freetype requirements (darwinports, fink,
 /usr/X11R6) and the different architectures (e.g., x86, ppc, universal) and
 the different OSX version (e.g., 10.4 and 10.5). We recommend that you build
 the way we do for the OSX release: get the source from the tarball or the
-git repository and follow the instruction in :file:`README.osx`.
+git repository and install the required dependencies through a third-party
+package manager: two widely used package managers are homebrew, and MacPorts.


Suggest the was clarify that this whole section is for is when you're not using conda

Also suggest:
"through a third-party package manager such as homebrew <https://brew.sh/>_ or MacPorts <https://www.macports.org/>_"

I think this whole document needs to be consolidated.

phobson · 2017-03-09T05:14:03Z

INSTALL

+without fiddling with environment variables::
+
+  # create a new environment with the required packages
+  conda create  -n "matplotlib_build" python=3.4 numpy python-dateutil pyparsing pytz tornado "cycler>=0.10" tk libpng zlib freetype


python=3.5 per the previous sentence?

tacaswell · 2017-03-11T22:15:24Z

INSTALL

+Matplotlib and most of its dependencies all available as wheel packages for
+OSX, windows and many linux distributions::
+
+  pip install -U numpy scipy scikit-learn


should this just be pip install -U matplotlib ?

Yep it should… copy paste gone wrong.

tacaswell · 2017-03-11T22:17:05Z

INSTALL

+optional Matplotlib backends and the capabilities they provide.
+
+  * :term:`tk` (>= 8.3, != 8.6.0 or 8.6.1): for the TkAgg backend;
+  * :term:`pyqt` (>= 4.4): for the Qt4Agg backend;


should mention qt5 as well. I could have sworn that this already said both...

well… we have another section where we list dependencies: it is mentioned there.

Actually, there are many optional dependencies missing from this list. Aren't pycairo and pyside also optional dependencies?

tacaswell · 2017-03-11T22:17:39Z

INSTALL

+  * `six <https://pypi.python.org/pypi/six>`_
+  * `backports.functools_lru_cache <https://pypi.python.org/pypi/backports.functools_lru_cache>`_
+    (for Python 2.7 only)
+  * `subprocess32 <https://pypi.python.org/pypi/subprocess32/>`_ (for Python


the '*nix' got dropped here.

NelleV · 2017-03-11T22:18:54Z

So @tacaswell 's review underlined that we list dependencies twice: once for everything, and another time for windows. I'll try to consolidate this.

tacaswell · 2017-03-11T22:20:08Z

INSTALL

+
+  * :term:`tk` (>= 8.3, != 8.6.0 or 8.6.1): for the TkAgg backend;
+  * :term:`pyqt` (>= 4.4): for the Qt4Agg backend;
+  * :term:`pygtk` (>= 2.4): for the GTK and the GTKAgg backend;


did we lose pygtk3 at somepoint? I have lost track of exactly how that is packaged at this point...

tacaswell · 2017-03-11T22:23:29Z

INSTALL

-
-
-Required libraries that ship with matplotlib
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


Probably should keep this section someplace.

anntzer · 2017-03-11T22:43:22Z

Minor suggestion: can you rename INSTALL to INSTALL.rst? This will render it properly on github and syntax-highlight it correctly on editors that can.

This is also consistent with having README.rst.

NelleV · 2017-03-11T22:46:11Z

I am wondering what people think of moving this file down to the documentation folder. It's barely readable as a text file as it has a lot of sphinx-specific syntax. We could then refer to it in the README.rst.

tacaswell · 2017-03-11T23:04:49Z

There is a pretty strong tradition of having a top-level INSTALL file. Adding the rst extenstion is reasonable

NelleV · 2017-03-11T23:07:32Z

OK, so I renamed it to INSTALL.rst.

I think this PR is good to go for a review. Our installation instructions do need a lot of love, and I think this is just a first pass on it.

NelleV · 2017-03-15T16:53:43Z

INSTALL.rst

+Matplotlib and most of its dependencies all available as wheel packages for
+OSX, windows and many linux distributions::
+
+  pip install -U matplotlib


This is true for linux and osx, but it'd be nice to check for windows!

NelleV · 2017-03-15T16:57:02Z

INSTALL.rst

@@ -0,0 +1,363 @@
+.. The source of this document is INSTALL. During the doc build process,


This needs to be updated.

NelleV · 2017-03-16T18:28:19Z

@anntzer the command pip install matplotlib does work out of the box on windows. So I think everything is correct in this PR.

anntzer · 2017-03-16T18:32:56Z

INSTALL.rst

+Installing an official release
+==============================
+
+Matplotlib and most of its dependencies all available as wheel packages for


anntzer · 2017-03-16T18:34:04Z

INSTALL.rst

+==============================
+
+Matplotlib and most of its dependencies all available as wheel packages for
+OSX, windows and many linux distributions::


"and Linux distributions" (sure manylinux technically doesn't cover very old distros but I guess very old macos are likewise not supported too...)
(capitalize Linux for consistency with below)

anntzer · 2017-03-16T18:34:24Z

INSTALL.rst

+=======================================
+
+Scientific Python distributions: Conda, Canopy...
+--------------------------------------------------


one too many "-"

anntzer · 2017-03-16T18:38:39Z

INSTALL.rst

+is packaged for almost every major Linux distribution.
+
+* Debian / Ubuntu : ``sudo apt-get install python-matplotlib``
+* Fedora / Redhat : ``sudo yum install python-matplotlib``


Red Hat.

on Arch, sudo pacman -S python-matplotlib (if you care to add it)

Depending on the distro it may be either python-matplotlib/python2-matplotlib (e.g. Fedora, Arch) or python-matplotlib/python3-matplotlib. Check at https://pkgs.org/download/matplotlib.

anntzer · 2017-03-16T18:39:22Z

INSTALL.rst

+
+We strongly recommend using `scipy-stack compatible Python distributions
+<http://www.scipy.org/install.html>`_ such as WinPython, Python(x,y),
+Enthought Canopy, or Continuum Anaconda, which have Matplotlib and many of its


... and its dependencies ("many" implies some are missing?)

I am fine changing this (this was not written by me), though I have no clue whether all of these include all dependencies.

I think we shouldn't recommend Python(x,y) any more - it is only Python 2.7.

anntzer · 2017-03-16T18:50:41Z

INSTALL.rst

+  * `ImageMagick <http://www.imagemagick.org/script/index.php>`__ (for saving
+    animated gifs);
+  * `Pillow <http://python-pillow.org/>`__ (for a larger selection of image
+    file format: JPEG, BMP, and TIFF image files);


"formats". Also only needed for reading, IIRC?

That would be surprising. I think it is for IO, but both reading and writing though I have no clue on that one.

eh "I think it is for all IO, so both reading and writing"…

I don't think we can write to all these image formats, can we?

Indeed we can't:

In [1]: fig, ax = plt.subplots() a In [2]: ax.plot(np.arange(100)) Out[2]: [<matplotlib.lines.Line2D at 0x7fe9a1b02048>] In [3]: fig.savefig("test.jpeg") In [4]: fig.savefig("test.bmp") --------------------------------------------------------------------------- ValueError Traceback (most recent call last) <ipython-input-4-25b9508e5148> in <module>() ----> 1 fig.savefig("test.bmp") /home/nelle/Projects/matplotlib/lib/matplotlib/figure.py in savefig(self, *args, **kwargs) 1761 self.set_frameon(frameon) 1762 -> 1763 self.canvas.print_figure(*args, **kwargs) 1764 1765 if frameon: /home/nelle/Projects/matplotlib/lib/matplotlib/backend_bases.py in print_figure(self, filename, dpi, facecolor, edgecolor, orientation, format, **kwargs) 2132 2133 # get canvas object and print method for format -> 2134 canvas = self._get_output_canvas(format) 2135 print_method = getattr(canvas, 'print_%s' % format) 2136 /home/nelle/Projects/matplotlib/lib/matplotlib/backend_bases.py in _get_output_canvas(self, format) 2075 raise ValueError('Format "%s" is not supported.\n' 2076 'Supported formats: ' -> 2077 '%s.' % (format, ', '.join(formats))) 2078 2079 def print_figure(self, filename, dpi=None, facecolor=None, edgecolor=None, ValueError: Format "bmp" is not supported. Supported formats: eps, jpeg, jpg, pdf, pgf, png, ps, raw, rgba, svg, svgz, tif, tiff.

Well, more specifically, we can't write to BMP, but the rest is apparently fine (I do have pillow installed).

anntzer · 2017-03-16T18:52:14Z

INSTALL.rst

+
+The build situation on OSX is complicated by the various places one
+can get the libpng and freetype requirements (darwinports, fink,
+/usr/X11R6) and the different architectures (e.g., x86, ppc, universal) and


"and" -> ","
plus a second comma before the last "and" if you like oxford commas.

anntzer · 2017-03-16T18:52:44Z

INSTALL.rst

+the different OSX version (e.g., 10.4 and 10.5). We recommend that you build
+the way we do for the OSX release: get the source from the tarball or the
+git repository and install the required dependencies through a third-party
+package manager: two widely used package managers are homebrew, and MacPorts.


Two colons in this sentence.

anntzer · 2017-03-16T18:53:02Z

INSTALL.rst

+The following example illustrates how to install libpng and freetype using
+brew:
+
+Example usage::


Remove "example usage" here and below, tuck the :: to the previous paragraph.

anntzer · 2017-03-16T18:54:08Z

INSTALL.rst

+
+The commands below assume that you can compile a native python lib for the python version of your
+choice. See `this howto <http://blog.ionelmc.ro/2014/12/21/compiling-python-extensions-on-windows/>`_
+how to install and setup such environments. If in doubt: use python 3.5 as it mostly works


Python 3.5+

NelleV · 2017-03-16T19:27:49Z

Thanks for the review @anntzer . I fixed most of the comments.

anntzer

just added a few more (tiny) apples

anntzer · 2017-03-16T21:24:45Z

INSTALL.rst

+For `standard Python <https://www.python.org/downloads/>`_ installations,
+install Matplotlib using pip_::
+
+    python -m pip install -U pip setuptools


make this pip install ... as well for consistency with above then?

anntzer · 2017-03-16T21:27:12Z

README.rst

+Matplotlib is a Python 2D plotting library which produces publication-quality
+figures in a variety of hardcopy formats and interactive environments across
+platforms. Matplotlib can be used in Python scripts, the Python and IPython
+shell (ala MATLAB or Mathematica), web application servers, and various


you know how to spell "à la" (it's correct even in English, see https://en.wiktionary.org/wiki/%C3%A0_la)

@QuLogic is going to do a pass over it, but it might be easier for me to fix this one considering my awesome french keyboard (Yéǎh¡!).
I'll do another pass tonight to check for this particular point )

QuLogic

I will make the minor modifications directly, but here are some wider reaching comments.

QuLogic · 2017-03-16T22:18:46Z

INSTALL.rst

+==============================
+
+Matplotlib and most of its dependencies arr all available as wheel packages for
+OSX, windows and Linux distributions::


Should we change OSX to macOS?

I think so, yes.

QuLogic · 2017-03-16T22:34:42Z

INSTALL.rst

+
+Since there is no canonical Windows package manager, the methods for building
+freetype, zlib, and libpng from source code are documented as a build script
+at `matplotlib-winbuild <https://github.com/jbmohler/matplotlib-winbuild>`_.


Should we import this into the Matplotlib organization?

I am actually slightly worried that this repository is totally out of date. It hasn't bee updated in 2014, so there is maybe a bit of work to be done to have the scripts run.

NelleV · 2017-03-16T23:15:11Z

INSTALL.rst

+at `matplotlib-winbuild <https://github.com/jbmohler/matplotlib-winbuild>`_.
+
+
+There are a few possibilities to build matplotlib on Windows:


matplotlib -> Matplotlib

Yep, I've fixed all of these (locally).

anntzer · 2017-03-19T19:18:51Z

INSTALL.rst

+    :ref:`install the latest development version<install_from_source>`.
+
+
+.. contents..


should be a colon? http://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html#explicit-links
or just drop this target?

It should. It is really strange that it compiled properly.

It turned into a comment (which explains the colour on GitHub now.)

NelleV · 2017-03-19T19:28:06Z

@anntzer It's fixed.

ngoldbaum · 2017-03-20T18:19:43Z

README.rst


-For installation instructions and requirements, see the INSTALL file or the `install <http://matplotlib.org/users/installing.html>`_ documentation. If you think you may want to contribute to matplotlib, check out the `guide to working with the source code <http://matplotlib.org/devel/gitwash/index.html>`_.
+For installation instructions and requirements, see the INSTALL file or the


isn't it called INSTALL.rst in this PR now?

.. contents.. -> .. contents::

NelleV added the Documentation label Mar 8, 2017

phobson reviewed Mar 9, 2017

View reviewed changes

tacaswell reviewed Mar 11, 2017

View reviewed changes

NelleV changed the title ~~DOC refactored installation instruction~~ [MRG] DOC refactored installation instruction Mar 11, 2017

NelleV commented Mar 15, 2017

View reviewed changes

anntzer requested changes Mar 16, 2017

View reviewed changes

QuLogic reviewed Mar 16, 2017

View reviewed changes

NelleV commented Mar 16, 2017

View reviewed changes

anntzer requested changes Mar 19, 2017

View reviewed changes

anntzer approved these changes Mar 20, 2017

View reviewed changes

NelleV changed the title ~~[MRG] DOC refactored installation instruction~~ [MRG+1] DOC refactored installation instruction Mar 20, 2017

ngoldbaum reviewed Mar 20, 2017

View reviewed changes

NelleV added 4 commits March 20, 2017 12:08

DOC refactored installation instruction

0acf41e

DOC improved our installation documentation

b55412e

DOC Completed the list of optional dependencies

3044d12

MAINT renamed INSTALL into INSTALL.rst for rendering

60a1b64

NelleV and others added 9 commits March 20, 2017 12:08

DOC fix typos and minor detail in installation.rst

36a917c

Use more https in install docs.

f55ed17

Use consistent capitalization in install instructions.

37af9a6

Use dnf for Fedora install instructions.

8ee8a93

Rename OSX to macOS for install instructions.

1159085

Tweak phrasing of install instructions.

86be684

DOC: Fix broken cross-reference.

9265b4a

FIX table of contents on INSTALL.rst

bafe158

.. contents.. -> .. contents::

DOC fix README refers to INSTALL.rst

dd08c3b

phobson merged commit 43ac39b into matplotlib:master Mar 23, 2017

phobson changed the title ~~[MRG+1] DOC refactored installation instruction~~ DOC refactored installation instruction Mar 23, 2017

QuLogic added this to the 2.1 (next point release) milestone Mar 23, 2017

NelleV deleted the installation_instructions branch April 8, 2017 20:28



		Required libraries that ship with matplotlib
		^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

		@@ -0,0 +1,363 @@
		.. The source of this document is INSTALL. During the doc build process,

		at `matplotlib-winbuild <https://github.com/jbmohler/matplotlib-winbuild>`_.


		There are a few possibilities to build matplotlib on Windows:

		:ref:`install the latest development version<install_from_source>`.


		.. contents..


		For installation instructions and requirements, see the INSTALL file or the `install <http://matplotlib.org/users/installing.html>`_ documentation. If you think you may want to contribute to matplotlib, check out the `guide to working with the source code <http://matplotlib.org/devel/gitwash/index.html>`_.
		For installation instructions and requirements, see the INSTALL file or the

DOC refactored installation instruction #8240

DOC refactored installation instruction #8240

Conversation

NelleV commented Mar 8, 2017

phobson left a 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

Choose a reason for hiding this comment

Choose a reason for hiding this comment

NelleV commented Mar 11, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

anntzer commented Mar 11, 2017

NelleV commented Mar 11, 2017

tacaswell commented Mar 11, 2017

NelleV commented Mar 11, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

NelleV commented Mar 16, 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

anntzer Mar 16, 2017 • edited Loading

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

NelleV commented Mar 16, 2017

anntzer left a 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

QuLogic left a 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

Choose a reason for hiding this comment

NelleV commented Mar 19, 2017

Choose a reason for hiding this comment

anntzer Mar 16, 2017 •

edited

Loading