Source code for sphinx_gallery.directives

"""
Custom Sphinx directives
========================
"""

import os

from docutils import statemachine
from docutils.parsers.rst import Directive, directives


[docs]class MiniGallery(Directive): """ Custom directive to insert a mini-gallery The required argument is one or more fully qualified names of objects, separated by spaces. The mini-gallery will be the subset of gallery examples that make use of that object (from that specific namespace). Options: * `add-heading` adds a heading to the mini-gallery. If an argument is provided, it uses that text for the heading. Otherwise, it uses default text. * `heading-level` specifies the heading level of the heading as a single character. If omitted, the default heading level is `'^'`. """ required_arguments = 1 optional_arguments = 0 final_argument_whitespace = True option_spec = {'add-heading': directives.unchanged, 'heading-level': directives.single_char_or_unicode} def run(self): # Respect the same disabling options as the `raw` directive if (not self.state.document.settings.raw_enabled or not self.state.document.settings.file_insertion_enabled): raise self.warning('"%s" directive disabled.' % self.name) # Retrieve the backreferences directory config = self.state.document.settings.env.config backreferences_dir = config.sphinx_gallery_conf['backreferences_dir'] # Parse the argument into the individual objects obj_list = self.arguments[0].split() lines = [] # Add a heading if requested if 'add-heading' in self.options: heading = self.options['add-heading'] if heading == "": if len(obj_list) == 1: heading = 'Examples using ``{}``'.format(obj_list[0]) else: heading = 'Examples using one of multiple objects' lines.append(heading) heading_level = self.options.get('heading-level', '^') lines.append(heading_level * len(heading)) # Insert the backreferences file(s) using the `include` directive for obj in obj_list: path = os.path.join('/', # Sphinx treats this as the source dir backreferences_dir, '{}.examples'.format(obj)) # Always remove the heading (first 5 lines) from the file lines.append('.. include:: {}\n :start-line: 5'.format(path)) # Insert the end for the gallery using the `raw` directive lines.append('.. raw:: html\n\n <div class="sphx-glr-clear"></div>') # Parse the assembly of `include` and `raw` directives text = '\n'.join(lines) include_lines = statemachine.string2lines(text, convert_whitespace=True) self.state_machine.insert_input(include_lines, path) return []