Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit b472516

Browse files
mdboommdboom
committed
Massive documentation build improvements. See e-mail on matplotlib-devel.
svn path=/branches/v0_98_5_maint/; revision=6652
1 parent 73468b7 commit b472516

10 files changed

Lines changed: 305 additions & 878 deletions

File tree

‎doc/README.txt‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,3 +35,7 @@ required), then type "python make.py html" in this directory. Wait
3535
for the initial run (which builds the example gallery) to be done,
3636
then run "python make.py html" again. The top file of the results will
3737
be ./build/html/index.html
38+
39+
To build a smaller version of the documentation (without
40+
high-resolution PNGs and PDF examples), type "python make.py --small
41+
html".

‎doc/_templates/gallery.html‎

Lines changed: 0 additions & 526 deletions
This file was deleted.

‎doc/_templates/gen_gallery.py‎

Lines changed: 0 additions & 91 deletions
This file was deleted.

‎doc/conf.py‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,8 @@
2828
# Add any Sphinx extension module names here, as strings. They can be extensions
2929
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
3030
extensions = ['mathmpl', 'math_symbol_table', 'sphinx.ext.autodoc',
31-
'only_directives', 'plot_directive', 'inheritance_diagram']
31+
'only_directives', 'plot_directive', 'inheritance_diagram',
32+
'gen_gallery']
3233

3334
# Add any paths that contain templates here, relative to this directory.
3435
templates_path = ['_templates']
@@ -75,6 +76,10 @@
7576
# The name of the Pygments (syntax highlighting) style to use.
7677
pygments_style = 'sphinx'
7778

79+
# Plot directive configuration
80+
# ----------------------------
81+
82+
plot_formats = ['png', 'hires.png', 'pdf']
7883

7984
# Options for HTML output
8085
# -----------------------

‎doc/make.py‎

Lines changed: 10 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -32,29 +32,24 @@ def examples():
3232
os.system('cd examples; svn-clean; python gen_rst.py')
3333
#pass
3434

35-
def gallery():
36-
'make the thumbnail gallery'
37-
os.system('cd _templates; python gen_gallery.py')
38-
39-
4035
def html():
4136
check_build()
4237
if not os.path.exists('examples/index.rst'):
4338
examples()
4439
shutil.copy('../lib/matplotlib/mpl-data/matplotlibrc', '_static/matplotlibrc')
4540
#figs()
46-
if os.system('sphinx-build -b html -d build/doctrees . build/html'):
41+
if small_docs:
42+
options = "-D plot_formats=\"['png']\""
43+
else:
44+
options = ''
45+
if os.system('sphinx-build %s -b html -d build/doctrees . build/html' % options):
4746
raise SystemExit("Building HTML failed.")
4847

4948
figures_dest_path = 'build/html/pyplots'
5049
if os.path.exists(figures_dest_path):
5150
shutil.rmtree(figures_dest_path)
5251
shutil.copytree('pyplots', figures_dest_path)
5352

54-
# rebuild the gallery
55-
gallery()
56-
print 'Just rebuilt gallery, you may need to make html again'
57-
5853
def latex():
5954
check_build()
6055
#figs()
@@ -96,12 +91,16 @@ def all():
9691
'sf' : sf,
9792
'sfpdf' : sfpdf,
9893
'examples' : examples,
99-
'gallery' : gallery,
10094
'all' : all,
10195
}
10296

10397

10498
if len(sys.argv)>1:
99+
if '--small' in sys.argv[1:]:
100+
small_docs = True
101+
sys.argv.remove('--small')
102+
else:
103+
small_docs = False
105104
for arg in sys.argv[1:]:
106105
func = funcd.get(arg)
107106
if func is None:

‎doc/sphinxext/gen_gallery.py‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
# generate a thumbnail gallery of examples
2+
template = """\
3+
{%% extends "layout.html" %%}
4+
{%% set title = "Thumbnail gallery" %%}
5+
6+
7+
{%% block body %%}
8+
9+
<h3>Click on any image to see full size image and source code</h3>
10+
<br/>
11+
12+
%s
13+
{%% endblock %%}
14+
"""
15+
16+
import os, glob, re, sys, warnings
17+
import matplotlib.image as image
18+
19+
multiimage = re.compile('(.*)_\d\d')
20+
21+
def gen_gallery(app, doctree):
22+
if app.builder.name != 'html':
23+
return
24+
25+
outdir = app.builder.outdir
26+
rootdir = 'plot_directive/mpl_examples'
27+
28+
# images we want to skip for the gallery because they are an unusual
29+
# size that doesn't layout well in a table, or because they may be
30+
# redundant with other images or uninteresting
31+
skips = set([
32+
'mathtext_examples',
33+
'matshow_02',
34+
'matshow_03',
35+
'matplotlib_icon',
36+
])
37+
38+
print
39+
print "generating gallery: ",
40+
data = []
41+
for subdir in ('api', 'pylab_examples', 'widgets'):
42+
origdir = os.path.join('build', rootdir, subdir)
43+
thumbdir = os.path.join(outdir, rootdir, subdir, 'thumbnails')
44+
if not os.path.exists(thumbdir):
45+
os.makedirs(thumbdir)
46+
print subdir,
47+
48+
for filename in sorted(glob.glob(os.path.join(origdir, '*.png'))):
49+
if filename.endswith("hires.png"):
50+
continue
51+
52+
path, filename = os.path.split(filename)
53+
basename, ext = os.path.splitext(filename)
54+
if basename in skips:
55+
sys.stdout.write('[skipping %s]' % basename)
56+
sys.stdout.flush()
57+
continue
58+
59+
# Create thumbnails based on images in tmpdir, and place
60+
# them within the build tree
61+
image.thumbnail(
62+
str(os.path.join(origdir, filename)),
63+
str(os.path.join(thumbdir, filename)),
64+
scale=0.3)
65+
66+
m = multiimage.match(basename)
67+
if m is None:
68+
pyfile = '%s.py'%basename
69+
else:
70+
basename = m.group(1)
71+
pyfile = '%s.py'%basename
72+
73+
data.append((subdir, basename,
74+
os.path.join(rootdir, subdir, 'thumbnails', filename)))
75+
76+
sys.stdout.write(".")
77+
sys.stdout.flush()
78+
print
79+
80+
link_template = """\
81+
<a href="%s"><img src="%s" border="0" alt="%s"/></a>
82+
"""
83+
84+
if len(data) == 0:
85+
warnings.warn("No thumbnails were found")
86+
87+
rows = []
88+
for (subdir, basename, thumbfile) in data:
89+
if thumbfile is not None:
90+
link = 'examples/%s/%s.html'%(subdir, basename)
91+
rows.append(link_template%(link, thumbfile, basename))
92+
93+
fh = file(os.path.join(app.builder.srcdir, '_templates', 'gallery.html'),
94+
'w')
95+
fh.write(template%'\n'.join(rows))
96+
fh.close()
97+
98+
def setup(app):
99+
app.connect('env-updated', gen_gallery)

‎doc/sphinxext/inheritance_diagram.py‎

Lines changed: 26 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -272,12 +272,16 @@ class inheritance_diagram(Body, Element):
272272
"""
273273
pass
274274

275-
def inheritance_diagram_directive_run(class_names, options, state):
275+
def inheritance_diagram_directive(name, arguments, options, content, lineno,
276+
content_offset, block_text, state,
277+
state_machine):
276278
"""
277279
Run when the inheritance_diagram directive is first encountered.
278280
"""
279281
node = inheritance_diagram()
280282

283+
class_names = arguments
284+
281285
# Create a graph starting with the list of classes
282286
graph = InheritanceGraph(class_names)
283287

@@ -310,15 +314,12 @@ def html_output_graph(self, node):
310314

311315
graph_hash = get_graph_hash(node)
312316
name = "inheritance%s" % graph_hash
313-
png_path = os.path.join('_static', name + ".png")
314-
315-
path = '_static'
316-
source = self.document.attributes['source']
317-
count = source.split('/doc/')[-1].count('/')
318-
for i in range(count):
319-
if os.path.exists(path): break
320-
path = '../'+path
321-
path = '../'+path #specifically added for matplotlib
317+
path = '_images'
318+
dest_path = os.path.join(setup.app.builder.outdir, path)
319+
if not os.path.exists(dest_path):
320+
os.makedirs(dest_path)
321+
png_path = os.path.join(dest_path, name + ".png")
322+
path = setup.app.builder.imgpath
322323

323324
# Create a mapping from fully-qualified class names to URLs.
324325
urls = {}
@@ -344,11 +345,14 @@ def latex_output_graph(self, node):
344345

345346
graph_hash = get_graph_hash(node)
346347
name = "inheritance%s" % graph_hash
347-
pdf_path = os.path.join('_static', name + ".pdf")
348+
dest_path = os.path.abspath(os.path.join(setup.app.builder.outdir, '_images'))
349+
if not os.path.exists(dest_path):
350+
os.makedirs(dest_path)
351+
pdf_path = os.path.abspath(os.path.join(dest_path, name + ".pdf"))
348352

349353
graph.run_dot(['-Tpdf', '-o%s' % pdf_path],
350354
name, parts, graph_options={'size': '"6.0,6.0"'})
351-
return '\\includegraphics{../../%s}' % pdf_path
355+
return '\\includegraphics{%s}' % pdf_path
352356

353357
def visit_inheritance_diagram(inner_func):
354358
"""
@@ -372,44 +376,14 @@ def visitor(self, node):
372376
def do_nothing(self, node):
373377
pass
374378

375-
options_spec = {
376-
'parts': directives.nonnegative_int
377-
}
378-
379-
# Deal with the old and new way of registering directives
380-
try:
381-
from docutils.parsers.rst import Directive
382-
except ImportError:
383-
from docutils.parsers.rst.directives import _directives
384-
def inheritance_diagram_directive(name, arguments, options, content, lineno,
385-
content_offset, block_text, state,
386-
state_machine):
387-
return inheritance_diagram_directive_run(arguments, options, state)
388-
inheritance_diagram_directive.__doc__ = __doc__
389-
inheritance_diagram_directive.arguments = (1, 100, 0)
390-
inheritance_diagram_directive.options = options_spec
391-
inheritance_diagram_directive.content = 0
392-
_directives['inheritance-diagram'] = inheritance_diagram_directive
393-
else:
394-
class inheritance_diagram_directive(Directive):
395-
has_content = False
396-
required_arguments = 1
397-
optional_arguments = 100
398-
final_argument_whitespace = False
399-
option_spec = options_spec
400-
401-
def run(self):
402-
return inheritance_diagram_directive_run(
403-
self.arguments, self.options, self.state)
404-
inheritance_diagram_directive.__doc__ = __doc__
405-
406-
directives.register_directive('inheritance-diagram',
407-
inheritance_diagram_directive)
408-
409379
def setup(app):
410-
app.add_node(inheritance_diagram,
411-
html=(visit_inheritance_diagram(html_output_graph),
412-
do_nothing))
413-
app.add_node(inheritance_diagram,
414-
latex=(visit_inheritance_diagram(latex_output_graph),
415-
do_nothing))
380+
setup.app = app
381+
setup.confdir = app.confdir
382+
383+
app.add_node(
384+
inheritance_diagram,
385+
latex=(visit_inheritance_diagram(latex_output_graph), do_nothing),
386+
html=(visit_inheritance_diagram(html_output_graph), do_nothing))
387+
app.add_directive(
388+
'inheritance-diagram', inheritance_diagram_directive,
389+
False, (1, 100, 0), parts = directives.nonnegative_int)

0 commit comments

Comments
 (0)