From ede19596ede452c90f1a9b24512c8e2931bc6d63 Mon Sep 17 00:00:00 2001 From: Nelle Varoquaux Date: Tue, 6 Sep 2016 09:30:49 -0700 Subject: [PATCH 1/4] DOC: documentated and simplified doc build - Removed basemap example, as it contains a basemap dependency. Basemap being currently quite hard to install, it adds unecessary burden for contributors to the documentation. - Documented the documentation build dependencies. - Checks that dependencies are installed *before* running the build. - Documented build options. fix #7040 --- doc/README.txt | 60 ++++++++++++++++++++++++++------------- doc/conf.py | 11 +++++++ doc/pyplots/plotmap.py | 49 -------------------------------- doc/users/screenshots.rst | 10 ------- 4 files changed, 52 insertions(+), 78 deletions(-) delete mode 100644 doc/pyplots/plotmap.py diff --git a/doc/README.txt b/doc/README.txt index 51c4b9093edd..e53e7324038a 100644 --- a/doc/README.txt +++ b/doc/README.txt @@ -1,11 +1,51 @@ maptlotlib documentation ======================== + +Building the documentation +-------------------------- + +Dependencies: + +* sphinx > 1.0 +* numpydoc +* ipython +* mock +* colorspacious + +All of these dependencies can be installed through pip:: + + pip install sphinx numpydoc ipython mock colorspacious + +or conda:: + + conda install sphinx numpydoc ipython mock colorspacious + +To build the HTML documentation, type ``python make.py html`` in this +directory. The top file of the results will be ./build/html/index.html + +**Note that Sphinx uses the installed version of the package to build the +documentation**: matplotlib must be installed *before* the docs can be +generated. Even if that is the case, one of the files needed to do this, +'../lib/matplotlib/mpl-data/matplotlibrc', is not version controlled, but +created when matplotlib is built. This means that the documentation cannot be +generated immediately after checking out the source code, even if matplotlib +is installed on your system: you will have to run ``python setup.py build`` +first. + +You can build the documentation with several options: + +* `--small` saves figures in low resolution. +* `--allowsphinxwarnings`: Don't turn Sphinx warnings into errors. +* `-n N` enables parallel build of the documentation using N process. + +Organization +------------- + This is the top level build directory for the matplotlib documentation. All of the documentation is written using sphinx, a python documentation system built on top of ReST. This directory contains - * users - the user documentation, e.g., plotting tutorials, configuration tips, etc. @@ -33,21 +73,3 @@ python documentation system built on top of ReST. This directory contains * mpl_examples - a link to the matplotlib examples in case any documentation wants to literal include them -To build the HTML documentation, install sphinx (1.0 or greater -required), then type "python make.py html" in this directory. Wait -for the initial run (which builds the example gallery) to be done, -then run "python make.py html" again. The top file of the results will -be ./build/html/index.html - -Note that Sphinx uses the installed version of the package to build -the documentation, so matplotlib must be installed *before* the docs -can be generated. Even if that is the case, one of the files needed -to do this, '../lib/matplotlib/mpl-data/matplotlibrc', is not version -controlled, but created when matplotlib is built. This means that the -documentation cannot be generated immediately after checking out the -source code, even if matplotlib is installed on your system: you will -have to run ``python setup.py build`` first. - -To build a smaller version of the documentation (without -high-resolution PNGs and PDF examples), type "python make.py --small -html". diff --git a/doc/conf.py b/doc/conf.py index 959363450c56..40f41e5bbac0 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -52,6 +52,17 @@ raise ImportError("No module named numpydoc - you need to install " "numpydoc to build the documentation.") +try: + import colorspacious +except ImportError: + raise ImportError("No module named colorspacious - you need to install " + "colorspacious to build the documentation") + +try: + import mock +except ImportError: + raise ImportError("No module named mock - you need to install " + "mock to build the documentation") autosummary_generate = True diff --git a/doc/pyplots/plotmap.py b/doc/pyplots/plotmap.py deleted file mode 100644 index 6ccb093de3cd..000000000000 --- a/doc/pyplots/plotmap.py +++ /dev/null @@ -1,49 +0,0 @@ -import matplotlib.pyplot as plt -import numpy as np - -from mpl_toolkits.basemap import Basemap - - -def plotmap(): - # create figure - fig = plt.figure(figsize=(8, 8)) - # set up orthographic map projection with - # perspective of satellite looking down at 50N, 100W. - # use low resolution coastlines. - map = Basemap(projection='ortho', lat_0=50, lon_0=-100, resolution='l') - # lat/lon coordinates of five cities. - lats = [40.02, 32.73, 38.55, 48.25, 17.29] - lons = [-105.16, -117.16, -77.00, -114.21, -88.10] - cities = ['Boulder, CO', 'San Diego, CA', - 'Washington, DC', 'Whitefish, MT', 'Belize City, Belize'] - # compute the native map projection coordinates for cities. - xc, yc = map(lons, lats) - # make up some data on a regular lat/lon grid. - nlats = 73 - nlons = 145 - delta = 2.*np.pi/(nlons-1) - lats = (0.5*np.pi-delta*np.indices((nlats,nlons))[0, :, :]) - lons = (delta*np.indices((nlats, nlons))[1, :, :]) - wave = 0.75*(np.sin(2.*lats)**8*np.cos(4.*lons)) - mean = 0.5*np.cos(2.*lats)*((np.sin(2.*lats))**2 + 2.) - # compute native map projection coordinates of lat/lon grid. - # (convert lons and lats to degrees first) - x, y = map(lons*180./np.pi, lats*180./np.pi) - # draw map boundary - map.drawmapboundary(color="0.9") - # draw graticule (latitude and longitude grid lines) - map.drawmeridians(np.arange(0, 360, 30), color="0.9") - map.drawparallels(np.arange(-90, 90, 30), color="0.9") - # plot filled circles at the locations of the cities. - map.plot(xc, yc, 'wo') - # plot the names of five cities. - for name, xpt, ypt in zip(cities, xc, yc): - plt.text(xpt+100000, ypt+100000, name, fontsize=9, color='w') - # contour data over the map. - cs = map.contour(x, y, wave+mean, 15, linewidths=1.5) - # draw blue marble image in background. - # (downsample the image by 50% for speed) - map.bluemarble(scale=0.5) - -plotmap() -plt.show() diff --git a/doc/users/screenshots.rst b/doc/users/screenshots.rst index acc5bd76e47e..ea619bf8736c 100644 --- a/doc/users/screenshots.rst +++ b/doc/users/screenshots.rst @@ -197,16 +197,6 @@ The following example emulates one of the financial plots in .. plot:: mpl_examples/pylab_examples/finance_work2.py - -.. _screenshots_basemap_demo: - -Basemap demo -============ - -Jeff Whitaker's :ref:`toolkit_basemap` add-on toolkit makes it possible to plot data on many different map projections. This example shows how to plot contours, markers and text on an orthographic projection, with NASA's "blue marble" satellite image as a background. - -.. plot:: pyplots/plotmap.py - .. _screenshots_log_demo: Log plots From 363ce544f9d44b577b5dba0eda7bb095ffa0a6a7 Mon Sep 17 00:00:00 2001 From: Matthew Brett Date: Tue, 6 Sep 2016 09:58:12 -0700 Subject: [PATCH 2/4] MAINT: add doc-requirements file Add pip requirements file for documentation dependencies. [skip ci] --- doc-requirements.txt | 13 +++++++++++++ 1 file changed, 13 insertions(+) create mode 100644 doc-requirements.txt diff --git a/doc-requirements.txt b/doc-requirements.txt new file mode 100644 index 000000000000..d46e9d830374 --- /dev/null +++ b/doc-requirements.txt @@ -0,0 +1,13 @@ +# Requirements for building docs +# You will first need a matching matplotlib installed +# e.g (from the matplotlib root directory) +# pip install -e . +# +# Install the documentation requirements with: +# pip install -r doc-requirements.txt +# +sphinx>1.0 +numpydoc +ipython +mock +colorspacious From faec918cf8de1445c7364b0ea637ec7b7662f705 Mon Sep 17 00:00:00 2001 From: Nelle Varoquaux Date: Tue, 6 Sep 2016 15:55:00 -0700 Subject: [PATCH 3/4] DOC documents the requirements.txt & updates travis - This PR documents the doc-requirements file and updates travis to use this file during the installation process. - Added pillow requirements. - Cleaned up conf.py a bit. --- .travis.yml | 9 +-------- doc-requirements.txt | 1 + doc/README.txt | 12 +++--------- doc/conf.py | 30 ++++++++++++++++-------------- 4 files changed, 21 insertions(+), 31 deletions(-) diff --git a/.travis.yml b/.travis.yml index 465c89a57948..9342444f8fca 100644 --- a/.travis.yml +++ b/.travis.yml @@ -113,7 +113,7 @@ install: - | # Install dependencies from pypi pip install $PRE python-dateutil $NUMPY pyparsing!=2.1.6 $PANDAS pep8 cycler coveralls coverage - pip install $PRE pillow sphinx!=1.3.0 $MOCK numpydoc ipython colorspacious + pip install $PRE -r doc-requirements.txt # Install nose from a build which has partial # support for python36 and suport for coverage output suppressing @@ -142,13 +142,6 @@ install: # Install matplotlib pip install -e . - | - # Installing basemap from github until it's back on pypi - # We have to install it after matplotlib to avoid pulling in MPL as - # a dependency - if [[ $BUILD_DOCS == true ]]; then - pip install pyshp!=1.2.8 - pip install git+https://github.com/matplotlib/basemap.git - fi; script: # The number of processes is hardcoded, because using too many causes the diff --git a/doc-requirements.txt b/doc-requirements.txt index d46e9d830374..9c2c189e9151 100644 --- a/doc-requirements.txt +++ b/doc-requirements.txt @@ -11,3 +11,4 @@ numpydoc ipython mock colorspacious +pillow diff --git a/doc/README.txt b/doc/README.txt index e53e7324038a..1a33488248dd 100644 --- a/doc/README.txt +++ b/doc/README.txt @@ -5,21 +5,15 @@ maptlotlib documentation Building the documentation -------------------------- -Dependencies: - -* sphinx > 1.0 -* numpydoc -* ipython -* mock -* colorspacious +A list of dependencies can be found in ../doc-requirements.txt. All of these dependencies can be installed through pip:: - pip install sphinx numpydoc ipython mock colorspacious + pip install -r ../doc-requirements.txt or conda:: - conda install sphinx numpydoc ipython mock colorspacious + conda install sphinx numpydoc ipython mock colorspacious pillow To build the HTML documentation, type ``python make.py html`` in this directory. The top file of the results will be ./build/html/index.html diff --git a/doc/conf.py b/doc/conf.py index 40f41e5bbac0..0982d6da5f32 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -59,10 +59,20 @@ "colorspacious to build the documentation") try: - import mock + from unittest.mock import MagicMock +except ImportError: + try: + from mock import MagicMock + except ImportError: + raise ImportError("No module named mock - you need to install " + "mock to build the documentation") + +try: + import matplotlib except ImportError: - raise ImportError("No module named mock - you need to install " - "mock to build the documentation") + msg = "Error: matplotlib must be installed before building the documentation" + sys.exit(msg) + autosummary_generate = True @@ -82,17 +92,14 @@ # General substitutions. project = 'Matplotlib' -copyright = '2002 - 2012 John Hunter, Darren Dale, Eric Firing, Michael Droettboom and the matplotlib development team; 2012 - 2014 The matplotlib development team' +copyright = ('2002 - 2012 John Hunter, Darren Dale, Eric Firing, ' + 'Michael Droettboom and the matplotlib development ' + 'team; 2012 - 2016 The matplotlib development team') # The default replacements for |version| and |release|, also used in various # other places throughout the built documents. # # The short X.Y version. -try: - import matplotlib -except ImportError: - msg = "Error: matplotlib must be installed before building the documentation" - sys.exit(msg) version = matplotlib.__version__ # The full version, including alpha/beta/rc tags. @@ -298,11 +305,6 @@ 1), ] -try: - from unittest.mock import MagicMock -except: - from mock import MagicMock - class MyWX(MagicMock): class Panel(object): From 633a2e4e2cc09d17bf721d85fcc173204c3d4e7b Mon Sep 17 00:00:00 2001 From: Nelle Varoquaux Date: Wed, 7 Sep 2016 09:17:01 -0700 Subject: [PATCH 4/4] FIX no need to build mpl before building the doc --- doc/README.txt | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/doc/README.txt b/doc/README.txt index 1a33488248dd..5a9f8187dcf1 100644 --- a/doc/README.txt +++ b/doc/README.txt @@ -20,12 +20,7 @@ directory. The top file of the results will be ./build/html/index.html **Note that Sphinx uses the installed version of the package to build the documentation**: matplotlib must be installed *before* the docs can be -generated. Even if that is the case, one of the files needed to do this, -'../lib/matplotlib/mpl-data/matplotlibrc', is not version controlled, but -created when matplotlib is built. This means that the documentation cannot be -generated immediately after checking out the source code, even if matplotlib -is installed on your system: you will have to run ``python setup.py build`` -first. +generated. You can build the documentation with several options: