DOC: documentated and simplified doc build

NelleV · NelleV · commit ede19596ede4 · 2016-09-07T01:23:51.000-07:00
- 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
diff --git 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
@@ -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
diff --git 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
