def gallery_code(examples_mod_name):
"""
Returns rst code suitable for generating a html gallery using sphinx.
examples_mod_name - the name of the importable (sub)module which contains
the examples
"""
# Store a dictionary mapping tag_name to (mod_name, mod_instance, tags)
examples_by_tag = {}
for mod_name, _, _, _ in walk_module(examples_mod_name):
if mod_name != examples_mod_name:
__import__(mod_name)
mod = sys.modules[mod_name]
tags = getattr(mod, '__tags__', ['Miscellanea'])
for tag in tags:
examples_by_tag.setdefault(tag, []).append((mod_name, mod))
result = ['Gallery',
'=======',
'Tags:\n',
'.. container:: inline-paragraphs\n'
]
examples_by_tag = sorted(examples_by_tag.iteritems(),
key=lambda pair: pair[0])
for tag, _ in examples_by_tag:
result.append('\t:ref:`gallery-tag-{}`\n'.format(tag))
for tag, mod_list in examples_by_tag:
result.extend(['.. _gallery-tag-{}:\n'.format(tag),
'{}'.format(tag),
'-' * len(tag) + '\n',
'.. container:: gallery_images\n'])
for (mod_name, mod) in mod_list:
safe_name, _ = safe_mod_name_and_fname(mod_name,
examples_mod_name)
# XXX The path is currently determined out of process by
# the plot directive. It would be nice to figure out the
# naming scheme to handle multiple plots in a single example.
img_path = 'examples/{}_01_00.png'.format(
mod_name.split('.')[-1])
thumb_path = 'examples/{}_01_00.thumb.png'.format(
mod_name.split('.')[-1])
entry = ["|image_{}|_\n".format(safe_name),
".. |image_{}| image:: {}".format(safe_name, thumb_path),
# XXX Hard-codes the html - rst cannot do nested inline
# elements (very well).
".. _image_{}: examples/{}.html".format(
safe_name, safe_name)]
result.extend(['\n\n\t' + line for line in entry])
return '\n'.join(result)
def examples_code(examples_mod_name,
source_directory,
output_directory='examples'):
"""
Generates the rst code for the given examples module.
examples_mod_name - the name of the parent (importable) module which
should be recursively walked when looking for
examples
source_directory - the path to the top level source directory containing
the rst content of the documentation
output_directory - the directory for the output to be put in. Should be
relative to the source_directory
"""
for mod_name, root_dir, fname, _ in walk_module(examples_mod_name):
if fname.startswith('__init__'):
continue
rst, rst_fname = individual_example_rst(mod_name, examples_mod_name,
output_directory)
rst_fname = os.path.join(source_directory, output_directory, rst_fname)
py_fname = os.path.join(source_directory, output_directory,
os.path.splitext(rst_fname)[0] + '.py')
if not os.path.isdir(os.path.dirname(py_fname)):
os.makedirs(os.path.dirname(py_fname))
if out_of_date(os.path.join(root_dir, fname), py_fname):
with open(os.path.join(root_dir, fname), 'r') as in_fh:
with open(py_fname, 'w') as out_fh:
for line in in_fh:
# Crudely remove the __tags__ line.
if line.startswith('__tags__ = '):
continue
out_fh.write(line)
if not same_contents(rst_fname, rst):
with open(rst_fname, 'w') as fh:
fh.write(rst)
def examples_code(examples_mod_name,
source_directory,
output_directory='examples'):
"""
Generates the rst code for the given examples module.
examples_mod_name - the name of the parent (importable) module which
should be recursively walked when looking for
examples
source_directory - the path to the top level source directory containing
the rst content of the documentation
output_directory - the directory for the output to be put in. Should be
relative to the source_directory
"""
for mod_name, root_dir, fname, _ in walk_module(examples_mod_name):
if fname.startswith('__init__'):
continue
rst, rst_fname = individual_example_rst(mod_name, examples_mod_name,
output_directory)
rst_fname = os.path.join(source_directory, output_directory, rst_fname)
py_fname = os.path.join(source_directory, output_directory,
os.path.splitext(rst_fname)[0] + '.py')
if not os.path.isdir(os.path.dirname(py_fname)):
os.makedirs(os.path.dirname(py_fname))
if out_of_date(os.path.join(root_dir, fname), py_fname):
with open(os.path.join(root_dir, fname), 'r') as in_fh:
with open(py_fname, 'w') as out_fh:
for line in in_fh:
# Crudely remove the __tags__ line.
if line.startswith('__tags__ = '):
continue
out_fh.write(line)
if not same_contents(rst_fname, rst):
with open(rst_fname, 'w') as fh:
fh.write(rst)
