Massive documentation build improvements. See e-mail on matplotlib-devel.

svn path=/branches/v0_98_5_maint/; revision=6652

Author: mdboom

doc/README.txt

@@ -35,3 +35,7 @@ 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
+
+To build a smaller version of the documentation (without
+high-resolution PNGs and PDF examples), type "python make.py --small
+html".

doc/_templates/gallery.html

@@ -28,7 +28,8 @@
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = ['mathmpl', 'math_symbol_table', 'sphinx.ext.autodoc',
-              'only_directives', 'plot_directive', 'inheritance_diagram']
+              'only_directives', 'plot_directive', 'inheritance_diagram',
+              'gen_gallery']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -75,6 +76,10 @@
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
+# Plot directive configuration
+# ----------------------------
+
+plot_formats = ['png', 'hires.png', 'pdf']
 
 # Options for HTML output
 # -----------------------

doc/_templates/gen_gallery.py

@@ -32,29 +32,24 @@ def examples():
     os.system('cd examples; svn-clean; python gen_rst.py')
     #pass
 
-def gallery():
-    'make the thumbnail gallery'
-    os.system('cd _templates; python gen_gallery.py')
-
-
 def html():
     check_build()
     if not os.path.exists('examples/index.rst'):
         examples()
     shutil.copy('../lib/matplotlib/mpl-data/matplotlibrc', '_static/matplotlibrc')
     #figs()
-    if os.system('sphinx-build -b html -d build/doctrees . build/html'):
+    if small_docs:
+        options = "-D plot_formats=\"['png']\""
+    else:
+        options = ''
+    if os.system('sphinx-build %s -b html -d build/doctrees . build/html' % options):
         raise SystemExit("Building HTML failed.")
 
     figures_dest_path = 'build/html/pyplots'
     if os.path.exists(figures_dest_path):
         shutil.rmtree(figures_dest_path)
     shutil.copytree('pyplots', figures_dest_path)
 
-    # rebuild the gallery
-    gallery()
-    print 'Just rebuilt gallery, you may need to make html again'
-
 def latex():
     check_build()
     #figs()
@@ -96,12 +91,16 @@ def all():
     'sf'       : sf,
     'sfpdf'    : sfpdf,
     'examples' : examples,
-    'gallery'  : gallery,
     'all'      : all,
     }
 
 
 if len(sys.argv)>1:
+    if '--small' in sys.argv[1:]:
+        small_docs = True
+        sys.argv.remove('--small')
+    else:
+        small_docs = False
     for arg in sys.argv[1:]:
         func = funcd.get(arg)
         if func is None:

doc/conf.py

@@ -0,0 +1,99 @@
+# generate a thumbnail gallery of examples
+template = """\
+{%% extends "layout.html" %%}
+{%% set title = "Thumbnail gallery" %%}
+
+
+{%% block body %%}
+
+<h3>Click on any image to see full size image and source code</h3>
+<br/>
+
+%s
+{%% endblock %%}
+"""
+
+import os, glob, re, sys, warnings
+import matplotlib.image as image
+
+multiimage = re.compile('(.*)_\d\d')
+
+def gen_gallery(app, doctree):
+    if app.builder.name != 'html':
+        return
+
+    outdir = app.builder.outdir
+    rootdir = 'plot_directive/mpl_examples'
+
+    # images we want to skip for the gallery because they are an unusual
+    # size that doesn't layout well in a table, or because they may be
+    # redundant with other images or uninteresting
+    skips = set([
+        'mathtext_examples',
+        'matshow_02',
+        'matshow_03',
+        'matplotlib_icon',
+        ])
+
+    print
+    print "generating gallery: ",
+    data = []
+    for subdir in ('api', 'pylab_examples', 'widgets'):
+        origdir = os.path.join('build', rootdir, subdir)
+        thumbdir = os.path.join(outdir, rootdir, subdir, 'thumbnails')
+        if not os.path.exists(thumbdir):
+            os.makedirs(thumbdir)
+        print subdir,
+
+        for filename in sorted(glob.glob(os.path.join(origdir, '*.png'))):
+            if filename.endswith("hires.png"):
+                continue
+
+            path, filename = os.path.split(filename)
+            basename, ext = os.path.splitext(filename)
+            if basename in skips:
+                sys.stdout.write('[skipping %s]' % basename)
+                sys.stdout.flush()
+                continue
+
+            # Create thumbnails based on images in tmpdir, and place
+            # them within the build tree
+            image.thumbnail(
+                str(os.path.join(origdir, filename)),
+                str(os.path.join(thumbdir, filename)),
+                scale=0.3)
+
+            m = multiimage.match(basename)
+            if m is None:
+                pyfile = '%s.py'%basename
+            else:
+                basename = m.group(1)
+                pyfile = '%s.py'%basename
+
+            data.append((subdir, basename,
+                         os.path.join(rootdir, subdir, 'thumbnails', filename)))
+
+            sys.stdout.write(".")
+            sys.stdout.flush()
+        print
+
+    link_template = """\
+    <a href="%s"><img src="%s" border="0" alt="%s"/></a>
+    """
+
+    if len(data) == 0:
+        warnings.warn("No thumbnails were found")
+
+    rows = []
+    for (subdir, basename, thumbfile) in data:
+        if thumbfile is not None:
+            link = 'examples/%s/%s.html'%(subdir, basename)
+            rows.append(link_template%(link, thumbfile, basename))
+
+    fh = file(os.path.join(app.builder.srcdir, '_templates', 'gallery.html'),
+              'w')
+    fh.write(template%'\n'.join(rows))
+    fh.close()
+
+def setup(app):
+    app.connect('env-updated', gen_gallery)

doc/make.py

@@ -272,12 +272,16 @@ class inheritance_diagram(Body, Element):
     """
     pass
 
-def inheritance_diagram_directive_run(class_names, options, state):
+def inheritance_diagram_directive(name, arguments, options, content, lineno,
+                                  content_offset, block_text, state,
+                                  state_machine):
     """
     Run when the inheritance_diagram directive is first encountered.
     """
     node = inheritance_diagram()
 
+    class_names = arguments
+
     # Create a graph starting with the list of classes
     graph = InheritanceGraph(class_names)
 
@@ -310,15 +314,12 @@ def html_output_graph(self, node):
 
     graph_hash = get_graph_hash(node)
     name = "inheritance%s" % graph_hash
-    png_path = os.path.join('_static', name + ".png")
-
-    path = '_static'
-    source = self.document.attributes['source']
-    count = source.split('/doc/')[-1].count('/')
-    for i in range(count):
-        if os.path.exists(path): break
-        path = '../'+path
-    path = '../'+path #specifically added for matplotlib
+    path = '_images'
+    dest_path = os.path.join(setup.app.builder.outdir, path)
+    if not os.path.exists(dest_path):
+        os.makedirs(dest_path)
+    png_path = os.path.join(dest_path, name + ".png")
+    path = setup.app.builder.imgpath
 
     # Create a mapping from fully-qualified class names to URLs.
     urls = {}
@@ -344,11 +345,14 @@ def latex_output_graph(self, node):
 
     graph_hash = get_graph_hash(node)
     name = "inheritance%s" % graph_hash
-    pdf_path = os.path.join('_static', name + ".pdf")
+    dest_path = os.path.abspath(os.path.join(setup.app.builder.outdir, '_images'))
+    if not os.path.exists(dest_path):
+        os.makedirs(dest_path)
+    pdf_path = os.path.abspath(os.path.join(dest_path, name + ".pdf"))
 
     graph.run_dot(['-Tpdf', '-o%s' % pdf_path],
                   name, parts, graph_options={'size': '"6.0,6.0"'})
-    return '\\includegraphics{../../%s}' % pdf_path
+    return '\\includegraphics{%s}' % pdf_path
 
 def visit_inheritance_diagram(inner_func):
     """
@@ -372,44 +376,14 @@ def visitor(self, node):
 def do_nothing(self, node):
     pass
 
-options_spec = {
-    'parts': directives.nonnegative_int
-    }
-
-# Deal with the old and new way of registering directives
-try:
-    from docutils.parsers.rst import Directive
-except ImportError:
-    from docutils.parsers.rst.directives import _directives
-    def inheritance_diagram_directive(name, arguments, options, content, lineno,
-                                      content_offset, block_text, state,
-                                      state_machine):
-        return inheritance_diagram_directive_run(arguments, options, state)
-    inheritance_diagram_directive.__doc__ = __doc__
-    inheritance_diagram_directive.arguments = (1, 100, 0)
-    inheritance_diagram_directive.options = options_spec
-    inheritance_diagram_directive.content = 0
-    _directives['inheritance-diagram'] = inheritance_diagram_directive
-else:
-    class inheritance_diagram_directive(Directive):
-        has_content = False
-        required_arguments = 1
-        optional_arguments = 100
-        final_argument_whitespace = False
-        option_spec = options_spec
-
-        def run(self):
-            return inheritance_diagram_directive_run(
-                self.arguments, self.options, self.state)
-    inheritance_diagram_directive.__doc__ = __doc__
-
-    directives.register_directive('inheritance-diagram',
-                                  inheritance_diagram_directive)
-
 def setup(app):
-    app.add_node(inheritance_diagram,
-                 html=(visit_inheritance_diagram(html_output_graph),
-                       do_nothing))
-    app.add_node(inheritance_diagram,
-                 latex=(visit_inheritance_diagram(latex_output_graph),
-                        do_nothing))
+    setup.app = app
+    setup.confdir = app.confdir
+
+    app.add_node(
+        inheritance_diagram,
+        latex=(visit_inheritance_diagram(latex_output_graph), do_nothing),
+        html=(visit_inheritance_diagram(html_output_graph), do_nothing))
+    app.add_directive(
+        'inheritance-diagram', inheritance_diagram_directive,
+        False, (1, 100, 0), parts = directives.nonnegative_int)