Merge pull request #7049 from NelleV/doc_readme

tacaswell · web-flow · commit 2d1e51fe81e4 · 2016-09-08T11:37:31.000-04:00
MNT: Documented dependencies to the doc and remove unnecessary dependencies
diff --git 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
@@ -0,0 +1,14 @@
+# 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
+pillow
diff --git a/doc/README.txt b/doc/README.txt
@@ -1,11 +1,40 @@
 maptlotlib documentation
 ========================
 
+
+Building the documentation
+--------------------------
+
+A list of dependencies can be found in ../doc-requirements.txt.
+
+All of these dependencies can be installed through pip::
+
+  pip install -r ../doc-requirements.txt
+
+or conda::
+
+  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
+
+**Note that Sphinx uses the installed version of the package to build the
+documentation**: matplotlib must be installed *before* the docs can be
+generated.
+
+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 +62,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
@@ -52,6 +52,27 @@
     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:
+    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:
+    msg = "Error: matplotlib must be installed before building the documentation"
+    sys.exit(msg)
+
 
 autosummary_generate = True
 
@@ -71,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.
@@ -287,11 +305,6 @@
      1),
 ]
 
-try:
-    from unittest.mock import MagicMock
-except:
-    from mock import MagicMock
-
 
 class MyWX(MagicMock):
     class Panel(object):
diff --git a/doc/pyplots/plotmap.py b/doc/pyplots/plotmap.py
diff --git a/doc/users/screenshots.rst b/doc/users/screenshots.rst
@@ -183,16 +183,6 @@ for both.
 See :mod:`matplotlib.ticker` and :mod:`matplotlib.dates` for details and usage.
 
 
-
-.. _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
