Merge pull request #1660 from vterron/master

mdboom · mdboom · commit ffdd946fe2e5 · 2013-01-23T09:43:39.000-08:00
Explain that matplotlib must be built before the HTML documentation
diff --git a/doc/README.txt b/doc/README.txt
@@ -39,6 +39,15 @@ 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
@@ -47,7 +47,12 @@
 # other places throughout the built documents.
 #
 # The short X.Y version.
-import matplotlib
+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.
 release = version
diff --git a/doc/make.py b/doc/make.py
@@ -110,7 +110,15 @@ def copytree(src, dst, symlinks=False, ignore=None):
 def copy_if_out_of_date(original, derived):
     if (not os.path.exists(derived) or
         os.stat(derived).st_mtime < os.stat(original).st_mtime):
-        shutil.copyfile(original, derived)
+        try:
+            shutil.copyfile(original, derived)
+        except IOError:
+            if os.path.basename(original) == 'matplotlibrc':
+                msg = "'%s' not found. " % original + \
+                      "Did you run `python setup.py build`?"
+                raise IOError(msg)
+            else:
+                raise
 
 def check_build():
     build_dirs = ['build', 'build/doctrees', 'build/html', 'build/latex',
