HW8 Complete

matPlotLib/env/lib/python3.7/site-packages/matplotlib/sphinxext/mathmpl.py

@@ -0,0 +1,141 @@
+import hashlib
+import os
+import sys
+
+from docutils import nodes
+from docutils.parsers.rst import Directive, directives
+import sphinx
+
+from matplotlib import rcParams
+from matplotlib import cbook
+from matplotlib.mathtext import MathTextParser
+rcParams['mathtext.fontset'] = 'cm'
+mathtext_parser = MathTextParser("Bitmap")
+
+
+# Define LaTeX math node:
+class latex_math(nodes.General, nodes.Element):
+    pass
+
+
+def fontset_choice(arg):
+    return directives.choice(arg, ['cm', 'stix', 'stixsans'])
+
+
+def math_role(role, rawtext, text, lineno, inliner,
+              options={}, content=[]):
+    i = rawtext.find('`')
+    latex = rawtext[i+1:-1]
+    node = latex_math(rawtext)
+    node['latex'] = latex
+    node['fontset'] = options.get('fontset', 'cm')
+    return [node], []
+math_role.options = {'fontset': fontset_choice}
+
+
+@cbook.deprecated("3.1", alternative="MathDirective")
+def math_directive(name, arguments, options, content, lineno,
+                   content_offset, block_text, state, state_machine):
+    latex = ''.join(content)
+    node = latex_math(block_text)
+    node['latex'] = latex
+    node['fontset'] = options.get('fontset', 'cm')
+    return [node]
+
+
+class MathDirective(Directive):
+    has_content = True
+    required_arguments = 0
+    optional_arguments = 0
+    final_argument_whitespace = False
+    option_spec = {'fontset': fontset_choice}
+
+    def run(self):
+        latex = ''.join(self.content)
+        node = latex_math(self.block_text)
+        node['latex'] = latex
+        node['fontset'] = self.options.get('fontset', 'cm')
+        return [node]
+
+
+# This uses mathtext to render the expression
+def latex2png(latex, filename, fontset='cm'):
+    latex = "$%s$" % latex
+    orig_fontset = rcParams['mathtext.fontset']
+    rcParams['mathtext.fontset'] = fontset
+    if os.path.exists(filename):
+        depth = mathtext_parser.get_depth(latex, dpi=100)
+    else:
+        try:
+            depth = mathtext_parser.to_png(filename, latex, dpi=100)
+        except Exception:
+            cbook._warn_external("Could not render math expression %s" % latex,
+                                 Warning)
+            depth = 0
+    rcParams['mathtext.fontset'] = orig_fontset
+    sys.stdout.write("#")
+    sys.stdout.flush()
+    return depth
+
+
+# LaTeX to HTML translation stuff:
+def latex2html(node, source):
+    inline = isinstance(node.parent, nodes.TextElement)
+    latex = node['latex']
+    name = 'math-%s' % hashlib.md5(latex.encode()).hexdigest()[-10:]
+
+    destdir = os.path.join(setup.app.builder.outdir, '_images', 'mathmpl')
+    if not os.path.exists(destdir):
+        os.makedirs(destdir)
+    dest = os.path.join(destdir, '%s.png' % name)
+    path = '/'.join((setup.app.builder.imgpath, 'mathmpl'))
+
+    depth = latex2png(latex, dest, node['fontset'])
+
+    if inline:
+        cls = ''
+    else:
+        cls = 'class="center" '
+    if inline and depth != 0:
+        style = 'style="position: relative; bottom: -%dpx"' % (depth + 1)
+    else:
+        style = ''
+
+    return '<img src="%s/%s.png" %s%s/>' % (path, name, cls, style)
+
+
+def setup(app):
+    setup.app = app
+
+    # Add visit/depart methods to HTML-Translator:
+    def visit_latex_math_html(self, node):
+        source = self.document.attributes['source']
+        self.body.append(latex2html(node, source))
+
+    def depart_latex_math_html(self, node):
+        pass
+
+    # Add visit/depart methods to LaTeX-Translator:
+    def visit_latex_math_latex(self, node):
+        inline = isinstance(node.parent, nodes.TextElement)
+        if inline:
+            self.body.append('$%s$' % node['latex'])
+        else:
+            self.body.extend(['\\begin{equation}',
+                              node['latex'],
+                              '\\end{equation}'])
+
+    def depart_latex_math_latex(self, node):
+        pass
+
+    app.add_node(latex_math,
+                 html=(visit_latex_math_html, depart_latex_math_html),
+                 latex=(visit_latex_math_latex, depart_latex_math_latex))
+    app.add_role('mathmpl', math_role)
+    app.add_directive('mathmpl', MathDirective)
+    if sphinx.version_info < (1, 8):
+        app.add_role('math', math_role)
+        app.add_directive('math', MathDirective)
+
+    metadata = {'parallel_read_safe': True, 'parallel_write_safe': True}
+    return metadata

matPlotLib/env/lib/python3.7/site-packages/matplotlib/sphinxext/plot_directive.py

@@ -0,0 +1,825 @@
+"""
+A directive for including a matplotlib plot in a Sphinx document.
+
+By default, in HTML output, `plot` will include a .png file with a
+link to a high-res .png and .pdf.  In LaTeX output, it will include a
+.pdf.
+
+The source code for the plot may be included in one of three ways:
+
+  1. **A path to a source file** as the argument to the directive::
+
+       .. plot:: path/to/plot.py
+
+     When a path to a source file is given, the content of the
+     directive may optionally contain a caption for the plot::
+
+       .. plot:: path/to/plot.py
+
+          This is the caption for the plot
+
+     Additionally, one may specify the name of a function to call (with
+     no arguments) immediately after importing the module::
+
+       .. plot:: path/to/plot.py plot_function1
+
+  2. Included as **inline content** to the directive::
+
+       .. plot::
+
+          import matplotlib.pyplot as plt
+          import matplotlib.image as mpimg
+          import numpy as np
+          img = mpimg.imread('_static/stinkbug.png')
+          imgplot = plt.imshow(img)
+
+  3. Using **doctest** syntax::
+
+       .. plot::
+          A plotting example:
+          >>> import matplotlib.pyplot as plt
+          >>> plt.plot([1,2,3], [4,5,6])
+
+Options
+-------
+
+The ``plot`` directive supports the following options:
+
+    format : {'python', 'doctest'}
+        Specify the format of the input
+
+    include-source : bool
+        Whether to display the source code. The default can be changed
+        using the `plot_include_source` variable in conf.py
+
+    encoding : str
+        If this source file is in a non-UTF8 or non-ASCII encoding,
+        the encoding must be specified using the `:encoding:` option.
+        The encoding will not be inferred using the ``-*- coding -*-``
+        metacomment.
+
+    context : bool or str
+        If provided, the code will be run in the context of all
+        previous plot directives for which the `:context:` option was
+        specified.  This only applies to inline code plot directives,
+        not those run from files. If the ``:context: reset`` option is
+        specified, the context is reset for this and future plots, and
+        previous figures are closed prior to running the code.
+        ``:context:close-figs`` keeps the context but closes previous figures
+        before running the code.
+
+    nofigs : bool
+        If specified, the code block will be run, but no figures will
+        be inserted.  This is usually useful with the ``:context:``
+        option.
+
+Additionally, this directive supports all of the options of the
+`image` directive, except for `target` (since plot will add its own
+target).  These include `alt`, `height`, `width`, `scale`, `align` and
+`class`.
+
+Configuration options
+---------------------
+
+The plot directive has the following configuration options:
+
+    plot_include_source
+        Default value for the include-source option
+
+    plot_html_show_source_link
+        Whether to show a link to the source in HTML.
+
+    plot_pre_code
+        Code that should be executed before each plot. If not specified or None
+        it will default to a string containing::
+
+            import numpy as np
+            from matplotlib import pyplot as plt
+
+    plot_basedir
+        Base directory, to which ``plot::`` file names are relative
+        to.  (If None or empty, file names are relative to the
+        directory where the file containing the directive is.)
+
+    plot_formats
+        File formats to generate. List of tuples or strings::
+
+            [(suffix, dpi), suffix, ...]
+
+        that determine the file format and the DPI. For entries whose
+        DPI was omitted, sensible defaults are chosen. When passing from
+        the command line through sphinx_build the list should be passed as
+        suffix:dpi,suffix:dpi, ....
+
+    plot_html_show_formats
+        Whether to show links to the files in HTML.
+
+    plot_rcparams
+        A dictionary containing any non-standard rcParams that should
+        be applied before each plot.
+
+    plot_apply_rcparams
+        By default, rcParams are applied when `context` option is not used in
+        a plot directive.  This configuration option overrides this behavior
+        and applies rcParams before each plot.
+
+    plot_working_directory
+        By default, the working directory will be changed to the directory of
+        the example, so the code can get at its data files, if any.  Also its
+        path will be added to `sys.path` so it can import any helper modules
+        sitting beside it.  This configuration option can be used to specify
+        a central directory (also added to `sys.path`) where data files and
+        helper modules for all code are located.
+
+    plot_template
+        Provide a customized template for preparing restructured text.
+"""
+
+import contextlib
+from io import StringIO
+import itertools
+import os
+from os.path import relpath
+from pathlib import Path
+import re
+import shutil
+import sys
+import textwrap
+import traceback
+import warnings
+
+from docutils.parsers.rst import directives, Directive
+from docutils.parsers.rst.directives.images import Image
+import jinja2  # Sphinx dependency.
+
+import matplotlib
+from matplotlib.backend_bases import FigureManagerBase
+try:
+    with warnings.catch_warnings(record=True):
+        warnings.simplefilter("error", UserWarning)
+        matplotlib.use('Agg')
+except UserWarning:
+    import matplotlib.pyplot as plt
+    plt.switch_backend("Agg")
+else:
+    import matplotlib.pyplot as plt
+from matplotlib import _pylab_helpers, cbook
+align = Image.align
+
+__version__ = 2
+
+
+# -----------------------------------------------------------------------------
+# Registration hook
+# -----------------------------------------------------------------------------
+
+
+@cbook.deprecated("3.1", alternative="PlotDirective")
+def plot_directive(name, arguments, options, content, lineno,
+                   content_offset, block_text, state, state_machine):
+    """Implementation of the ``.. plot::`` directive.
+
+    See the module docstring for details.
+    """
+    return run(arguments, content, options, state_machine, state, lineno)
+
+
+def _option_boolean(arg):
+    if not arg or not arg.strip():
+        # no argument given, assume used as a flag
+        return True
+    elif arg.strip().lower() in ('no', '0', 'false'):
+        return False
+    elif arg.strip().lower() in ('yes', '1', 'true'):
+        return True
+    else:
+        raise ValueError('"%s" unknown boolean' % arg)
+
+
+def _option_context(arg):
+    if arg in [None, 'reset', 'close-figs']:
+        return arg
+    raise ValueError("argument should be None or 'reset' or 'close-figs'")
+
+
+def _option_format(arg):
+    return directives.choice(arg, ('python', 'doctest'))
+
+
+def _option_align(arg):
+    return directives.choice(arg, ("top", "middle", "bottom", "left", "center",
+                                   "right"))
+
+
+def mark_plot_labels(app, document):
+    """
+    To make plots referenceable, we need to move the reference from
+    the "htmlonly" (or "latexonly") node to the actual figure node
+    itself.
+    """
+    for name, explicit in document.nametypes.items():
+        if not explicit:
+            continue
+        labelid = document.nameids[name]
+        if labelid is None:
+            continue
+        node = document.ids[labelid]
+        if node.tagname in ('html_only', 'latex_only'):
+            for n in node:
+                if n.tagname == 'figure':
+                    sectname = name
+                    for c in n:
+                        if c.tagname == 'caption':
+                            sectname = c.astext()
+                            break
+
+                    node['ids'].remove(labelid)
+                    node['names'].remove(name)
+                    n['ids'].append(labelid)
+                    n['names'].append(name)
+                    document.settings.env.labels[name] = \
+                        document.settings.env.docname, labelid, sectname
+                    break
+
+
+class PlotDirective(Directive):
+    """Implementation of the ``.. plot::`` directive.
+
+    See the module docstring for details.
+    """
+
+    has_content = True
+    required_arguments = 0
+    optional_arguments = 2
+    final_argument_whitespace = False
+    option_spec = {
+        'alt': directives.unchanged,
+        'height': directives.length_or_unitless,
+        'width': directives.length_or_percentage_or_unitless,
+        'scale': directives.nonnegative_int,
+        'align': _option_align,
+        'class': directives.class_option,
+        'include-source': _option_boolean,
+        'format': _option_format,
+        'context': _option_context,
+        'nofigs': directives.flag,
+        'encoding': directives.encoding,
+        }
+
+    def run(self):
+        """Run the plot directive."""
+        return run(self.arguments, self.content, self.options,
+                   self.state_machine, self.state, self.lineno)
+
+
+def setup(app):
+    import matplotlib
+    setup.app = app
+    setup.config = app.config
+    setup.confdir = app.confdir
+    app.add_directive('plot', PlotDirective)
+    app.add_config_value('plot_pre_code', None, True)
+    app.add_config_value('plot_include_source', False, True)
+    app.add_config_value('plot_html_show_source_link', True, True)
+    app.add_config_value('plot_formats', ['png', 'hires.png', 'pdf'], True)
+    app.add_config_value('plot_basedir', None, True)
+    app.add_config_value('plot_html_show_formats', True, True)
+    app.add_config_value('plot_rcparams', {}, True)
+    app.add_config_value('plot_apply_rcparams', False, True)
+    app.add_config_value('plot_working_directory', None, True)
+    app.add_config_value('plot_template', None, True)
+
+    app.connect('doctree-read', mark_plot_labels)
+
+    metadata = {'parallel_read_safe': True, 'parallel_write_safe': True,
+                'version': matplotlib.__version__}
+    return metadata
+
+
+# -----------------------------------------------------------------------------
+# Doctest handling
+# -----------------------------------------------------------------------------
+
+
+def contains_doctest(text):
+    try:
+        # check if it's valid Python as-is
+        compile(text, '<string>', 'exec')
+        return False
+    except SyntaxError:
+        pass
+    r = re.compile(r'^\s*>>>', re.M)
+    m = r.search(text)
+    return bool(m)
+
+
+def unescape_doctest(text):
+    """
+    Extract code from a piece of text, which contains either Python code
+    or doctests.
+    """
+    if not contains_doctest(text):
+        return text
+
+    code = ""
+    for line in text.split("\n"):
+        m = re.match(r'^\s*(>>>|\.\.\.) (.*)$', line)
+        if m:
+            code += m.group(2) + "\n"
+        elif line.strip():
+            code += "# " + line.strip() + "\n"
+        else:
+            code += "\n"
+    return code
+
+
+def split_code_at_show(text):
+    """Split code at plt.show()."""
+    parts = []
+    is_doctest = contains_doctest(text)
+
+    part = []
+    for line in text.split("\n"):
+        if (not is_doctest and line.strip() == 'plt.show()') or \
+               (is_doctest and line.strip() == '>>> plt.show()'):
+            part.append(line)
+            parts.append("\n".join(part))
+            part = []
+        else:
+            part.append(line)
+    if "\n".join(part).strip():
+        parts.append("\n".join(part))
+    return parts
+
+
+def remove_coding(text):
+    r"""Remove the coding comment, which six.exec\_ doesn't like."""
+    cbook.warn_deprecated('3.0', name='remove_coding', removal='3.1')
+    sub_re = re.compile(r"^#\s*-\*-\s*coding:\s*.*-\*-$", flags=re.MULTILINE)
+    return sub_re.sub("", text)
+
+
+# -----------------------------------------------------------------------------
+# Template
+# -----------------------------------------------------------------------------
+
+
+TEMPLATE = """
+{{ source_code }}
+
+.. only:: html
+
+   {% if source_link or (html_show_formats and not multi_image) %}
+   (
+   {%- if source_link -%}
+   `Source code <{{ source_link }}>`__
+   {%- endif -%}
+   {%- if html_show_formats and not multi_image -%}
+     {%- for img in images -%}
+       {%- for fmt in img.formats -%}
+         {%- if source_link or not loop.first -%}, {% endif -%}
+         `{{ fmt }} <{{ dest_dir }}/{{ img.basename }}.{{ fmt }}>`__
+       {%- endfor -%}
+     {%- endfor -%}
+   {%- endif -%}
+   )
+   {% endif %}
+
+   {% for img in images %}
+   .. figure:: {{ build_dir }}/{{ img.basename }}.{{ default_fmt }}
+      {% for option in options -%}
+      {{ option }}
+      {% endfor %}
+
+      {% if html_show_formats and multi_image -%}
+        (
+        {%- for fmt in img.formats -%}
+        {%- if not loop.first -%}, {% endif -%}
+        `{{ fmt }} <{{ dest_dir }}/{{ img.basename }}.{{ fmt }}>`__
+        {%- endfor -%}
+        )
+      {%- endif -%}
+
+      {{ caption }}
+   {% endfor %}
+
+.. only:: not html
+
+   {% for img in images %}
+   .. figure:: {{ build_dir }}/{{ img.basename }}.*
+      {% for option in options -%}
+      {{ option }}
+      {% endfor %}
+
+      {{ caption }}
+   {% endfor %}
+
+"""
+
+exception_template = """
+.. only:: html
+
+   [`source code <%(linkdir)s/%(basename)s.py>`__]
+
+Exception occurred rendering plot.
+
+"""
+
+# the context of the plot for all directives specified with the
+# :context: option
+plot_context = dict()
+
+
+class ImageFile(object):
+    def __init__(self, basename, dirname):
+        self.basename = basename
+        self.dirname = dirname
+        self.formats = []
+
+    def filename(self, format):
+        return os.path.join(self.dirname, "%s.%s" % (self.basename, format))
+
+    def filenames(self):
+        return [self.filename(fmt) for fmt in self.formats]
+
+
+def out_of_date(original, derived):
+    """
+    Return whether *derived* is out-of-date relative to *original*, both of
+    which are full file paths.
+    """
+    return (not os.path.exists(derived) or
+            (os.path.exists(original) and
+             os.stat(derived).st_mtime < os.stat(original).st_mtime))
+
+
+class PlotError(RuntimeError):
+    pass
+
+
+def run_code(code, code_path, ns=None, function_name=None):
+    """
+    Import a Python module from a path, and run the function given by
+    name, if function_name is not None.
+    """
+
+    # Change the working directory to the directory of the example, so
+    # it can get at its data files, if any.  Add its path to sys.path
+    # so it can import any helper modules sitting beside it.
+    pwd = os.getcwd()
+    if setup.config.plot_working_directory is not None:
+        try:
+            os.chdir(setup.config.plot_working_directory)
+        except OSError as err:
+            raise OSError(str(err) + '\n`plot_working_directory` option in'
+                          'Sphinx configuration file must be a valid '
+                          'directory path')
+        except TypeError as err:
+            raise TypeError(str(err) + '\n`plot_working_directory` option in '
+                            'Sphinx configuration file must be a string or '
+                            'None')
+    elif code_path is not None:
+        dirname = os.path.abspath(os.path.dirname(code_path))
+        os.chdir(dirname)
+
+    with cbook._setattr_cm(
+            sys, argv=[code_path], path=[os.getcwd(), *sys.path]), \
+            contextlib.redirect_stdout(StringIO()):
+        try:
+            code = unescape_doctest(code)
+            if ns is None:
+                ns = {}
+            if not ns:
+                if setup.config.plot_pre_code is None:
+                    exec('import numpy as np\n'
+                         'from matplotlib import pyplot as plt\n', ns)
+                else:
+                    exec(str(setup.config.plot_pre_code), ns)
+            if "__main__" in code:
+                ns['__name__'] = '__main__'
+
+            # Patch out non-interactive show() to avoid triggering a warning.
+            with cbook._setattr_cm(FigureManagerBase, show=lambda self: None):
+                exec(code, ns)
+                if function_name is not None:
+                    exec(function_name + "()", ns)
+
+        except (Exception, SystemExit) as err:
+            raise PlotError(traceback.format_exc())
+        finally:
+            os.chdir(pwd)
+    return ns
+
+
+def clear_state(plot_rcparams, close=True):
+    if close:
+        plt.close('all')
+    matplotlib.rc_file_defaults()
+    matplotlib.rcParams.update(plot_rcparams)
+
+
+def get_plot_formats(config):
+    default_dpi = {'png': 80, 'hires.png': 200, 'pdf': 200}
+    formats = []
+    plot_formats = config.plot_formats
+    for fmt in plot_formats:
+        if isinstance(fmt, str):
+            if ':' in fmt:
+                suffix, dpi = fmt.split(':')
+                formats.append((str(suffix), int(dpi)))
+            else:
+                formats.append((fmt, default_dpi.get(fmt, 80)))
+        elif isinstance(fmt, (tuple, list)) and len(fmt) == 2:
+            formats.append((str(fmt[0]), int(fmt[1])))
+        else:
+            raise PlotError('invalid image format "%r" in plot_formats' % fmt)
+    return formats
+
+
+def render_figures(code, code_path, output_dir, output_base, context,
+                   function_name, config, context_reset=False,
+                   close_figs=False):
+    """
+    Run a pyplot script and save the images in *output_dir*.
+
+    Save the images under *output_dir* with file names derived from
+    *output_base*
+    """
+    formats = get_plot_formats(config)
+
+    # -- Try to determine if all images already exist
+
+    code_pieces = split_code_at_show(code)
+
+    # Look for single-figure output files first
+    all_exists = True
+    img = ImageFile(output_base, output_dir)
+    for format, dpi in formats:
+        if out_of_date(code_path, img.filename(format)):
+            all_exists = False
+            break
+        img.formats.append(format)
+
+    if all_exists:
+        return [(code, [img])]
+
+    # Then look for multi-figure output files
+    results = []
+    all_exists = True
+    for i, code_piece in enumerate(code_pieces):
+        images = []
+        for j in itertools.count():
+            if len(code_pieces) > 1:
+                img = ImageFile('%s_%02d_%02d' % (output_base, i, j),
+                                output_dir)
+            else:
+                img = ImageFile('%s_%02d' % (output_base, j), output_dir)
+            for format, dpi in formats:
+                if out_of_date(code_path, img.filename(format)):
+                    all_exists = False
+                    break
+                img.formats.append(format)
+
+            # assume that if we have one, we have them all
+            if not all_exists:
+                all_exists = (j > 0)
+                break
+            images.append(img)
+        if not all_exists:
+            break
+        results.append((code_piece, images))
+
+    if all_exists:
+        return results
+
+    # We didn't find the files, so build them
+
+    results = []
+    if context:
+        ns = plot_context
+    else:
+        ns = {}
+
+    if context_reset:
+        clear_state(config.plot_rcparams)
+        plot_context.clear()
+
+    close_figs = not context or close_figs
+
+    for i, code_piece in enumerate(code_pieces):
+
+        if not context or config.plot_apply_rcparams:
+            clear_state(config.plot_rcparams, close_figs)
+        elif close_figs:
+            plt.close('all')
+
+        run_code(code_piece, code_path, ns, function_name)
+
+        images = []
+        fig_managers = _pylab_helpers.Gcf.get_all_fig_managers()
+        for j, figman in enumerate(fig_managers):
+            if len(fig_managers) == 1 and len(code_pieces) == 1:
+                img = ImageFile(output_base, output_dir)
+            elif len(code_pieces) == 1:
+                img = ImageFile("%s_%02d" % (output_base, j), output_dir)
+            else:
+                img = ImageFile("%s_%02d_%02d" % (output_base, i, j),
+                                output_dir)
+            images.append(img)
+            for format, dpi in formats:
+                try:
+                    figman.canvas.figure.savefig(img.filename(format), dpi=dpi)
+                except Exception as err:
+                    raise PlotError(traceback.format_exc())
+                img.formats.append(format)
+
+        results.append((code_piece, images))
+
+    if not context or config.plot_apply_rcparams:
+        clear_state(config.plot_rcparams, close=not context)
+
+    return results
+
+
+def run(arguments, content, options, state_machine, state, lineno):
+    document = state_machine.document
+    config = document.settings.env.config
+    nofigs = 'nofigs' in options
+
+    formats = get_plot_formats(config)
+    default_fmt = formats[0][0]
+
+    options.setdefault('include-source', config.plot_include_source)
+    keep_context = 'context' in options
+    context_opt = None if not keep_context else options['context']
+
+    rst_file = document.attributes['source']
+    rst_dir = os.path.dirname(rst_file)
+
+    if len(arguments):
+        if not config.plot_basedir:
+            source_file_name = os.path.join(setup.app.builder.srcdir,
+                                            directives.uri(arguments[0]))
+        else:
+            source_file_name = os.path.join(setup.confdir, config.plot_basedir,
+                                            directives.uri(arguments[0]))
+
+        # If there is content, it will be passed as a caption.
+        caption = '\n'.join(content)
+
+        # If the optional function name is provided, use it
+        if len(arguments) == 2:
+            function_name = arguments[1]
+        else:
+            function_name = None
+
+        code = Path(source_file_name).read_text(encoding='utf-8')
+        output_base = os.path.basename(source_file_name)
+    else:
+        source_file_name = rst_file
+        code = textwrap.dedent("\n".join(map(str, content)))
+        counter = document.attributes.get('_plot_counter', 0) + 1
+        document.attributes['_plot_counter'] = counter
+        base, ext = os.path.splitext(os.path.basename(source_file_name))
+        output_base = '%s-%d.py' % (base, counter)
+        function_name = None
+        caption = ''
+
+    base, source_ext = os.path.splitext(output_base)
+    if source_ext in ('.py', '.rst', '.txt'):
+        output_base = base
+    else:
+        source_ext = ''
+
+    # ensure that LaTeX includegraphics doesn't choke in foo.bar.pdf filenames
+    output_base = output_base.replace('.', '-')
+
+    # is it in doctest format?
+    is_doctest = contains_doctest(code)
+    if 'format' in options:
+        if options['format'] == 'python':
+            is_doctest = False
+        else:
+            is_doctest = True
+
+    # determine output directory name fragment
+    source_rel_name = relpath(source_file_name, setup.confdir)
+    source_rel_dir = os.path.dirname(source_rel_name)
+    while source_rel_dir.startswith(os.path.sep):
+        source_rel_dir = source_rel_dir[1:]
+
+    # build_dir: where to place output files (temporarily)
+    build_dir = os.path.join(os.path.dirname(setup.app.doctreedir),
+                             'plot_directive',
+                             source_rel_dir)
+    # get rid of .. in paths, also changes pathsep
+    # see note in Python docs for warning about symbolic links on Windows.
+    # need to compare source and dest paths at end
+    build_dir = os.path.normpath(build_dir)
+
+    if not os.path.exists(build_dir):
+        os.makedirs(build_dir)
+
+    # output_dir: final location in the builder's directory
+    dest_dir = os.path.abspath(os.path.join(setup.app.builder.outdir,
+                                            source_rel_dir))
+    if not os.path.exists(dest_dir):
+        os.makedirs(dest_dir)  # no problem here for me, but just use built-ins
+
+    # how to link to files from the RST file
+    dest_dir_link = os.path.join(relpath(setup.confdir, rst_dir),
+                                 source_rel_dir).replace(os.path.sep, '/')
+    try:
+        build_dir_link = relpath(build_dir, rst_dir).replace(os.path.sep, '/')
+    except ValueError:
+        # on Windows, relpath raises ValueError when path and start are on
+        # different mounts/drives
+        build_dir_link = build_dir
+    source_link = dest_dir_link + '/' + output_base + source_ext
+
+    # make figures
+    try:
+        results = render_figures(code,
+                                 source_file_name,
+                                 build_dir,
+                                 output_base,
+                                 keep_context,
+                                 function_name,
+                                 config,
+                                 context_reset=context_opt == 'reset',
+                                 close_figs=context_opt == 'close-figs')
+        errors = []
+    except PlotError as err:
+        reporter = state.memo.reporter
+        sm = reporter.system_message(
+            2, "Exception occurred in plotting {}\n from {}:\n{}".format(
+                output_base, source_file_name, err),
+            line=lineno)
+        results = [(code, [])]
+        errors = [sm]
+
+    # Properly indent the caption
+    caption = '\n'.join('      ' + line.strip()
+                        for line in caption.split('\n'))
+
+    # generate output restructuredtext
+    total_lines = []
+    for j, (code_piece, images) in enumerate(results):
+        if options['include-source']:
+            if is_doctest:
+                lines = ['', *code_piece.splitlines()]
+            else:
+                lines = ['.. code-block:: python', '',
+                         *textwrap.indent(code_piece, '    ').splitlines()]
+            source_code = "\n".join(lines)
+        else:
+            source_code = ""
+
+        if nofigs:
+            images = []
+
+        opts = [
+            ':%s: %s' % (key, val) for key, val in options.items()
+            if key in ('alt', 'height', 'width', 'scale', 'align', 'class')]
+
+        # Not-None src_link signals the need for a source link in the generated
+        # html
+        if j == 0 and config.plot_html_show_source_link:
+            src_link = source_link
+        else:
+            src_link = None
+
+        result = jinja2.Template(config.plot_template or TEMPLATE).render(
+            default_fmt=default_fmt,
+            dest_dir=dest_dir_link,
+            build_dir=build_dir_link,
+            source_link=src_link,
+            multi_image=len(images) > 1,
+            options=opts,
+            images=images,
+            source_code=source_code,
+            html_show_formats=config.plot_html_show_formats and len(images),
+            caption=caption)
+
+        total_lines.extend(result.split("\n"))
+        total_lines.extend("\n")
+
+    if total_lines:
+        state_machine.insert_input(total_lines, source=source_file_name)
+
+    # copy image files to builder's output directory, if necessary
+    Path(dest_dir).mkdir(parents=True, exist_ok=True)
+
+    for code_piece, images in results:
+        for img in images:
+            for fn in img.filenames():
+                destimg = os.path.join(dest_dir, os.path.basename(fn))
+                if fn != destimg:
+                    shutil.copyfile(fn, destimg)
+
+    # copy script (if necessary)
+    Path(dest_dir, output_base + source_ext).write_text(
+        unescape_doctest(code) if source_file_name == rst_file else code,
+        encoding='utf-8')
+
+    return errors

matPlotLib/env/lib/python3.7/site-packages/matplotlib/sphinxext/tests/__init__.py

@@ -0,0 +1 @@
+# Make tests a package

matPlotLib/env/lib/python3.7/site-packages/matplotlib/sphinxext/tests/conftest.py

@@ -0,0 +1,3 @@
+from matplotlib.testing.conftest import (mpl_test_settings,
+                                         mpl_image_comparison_parameters,
+                                         pytest_configure, pytest_unconfigure)

matPlotLib/env/lib/python3.7/site-packages/matplotlib/sphinxext/tests/test_tinypages.py

@@ -0,0 +1,53 @@
+"""Tests for tinypages build using sphinx extensions."""
+
+import filecmp
+from os.path import join as pjoin, dirname, isdir
+from subprocess import Popen, PIPE
+import sys
+
+import pytest
+
+
+pytest.importorskip('sphinx')
+
+
+def test_tinypages(tmpdir):
+    html_dir = pjoin(str(tmpdir), 'html')
+    doctree_dir = pjoin(str(tmpdir), 'doctrees')
+    # Build the pages with warnings turned into errors
+    cmd = [sys.executable, '-msphinx', '-W', '-b', 'html', '-d', doctree_dir,
+           pjoin(dirname(__file__), 'tinypages'), html_dir]
+    proc = Popen(cmd, stdout=PIPE, stderr=PIPE, universal_newlines=True)
+    out, err = proc.communicate()
+    assert proc.returncode == 0, \
+        "sphinx build failed with stdout:\n{}\nstderr:\n{}\n".format(out, err)
+    if err:
+        pytest.fail("sphinx build emitted the following warnings:\n{}"
+                    .format(err))
+
+    assert isdir(html_dir)
+
+    def plot_file(num):
+        return pjoin(html_dir, 'some_plots-{0}.png'.format(num))
+
+    range_10, range_6, range_4 = [plot_file(i) for i in range(1, 4)]
+    # Plot 5 is range(6) plot
+    assert filecmp.cmp(range_6, plot_file(5))
+    # Plot 7 is range(4) plot
+    assert filecmp.cmp(range_4, plot_file(7))
+    # Plot 11 is range(10) plot
+    assert filecmp.cmp(range_10, plot_file(11))
+    # Plot 12 uses the old range(10) figure and the new range(6) figure
+    assert filecmp.cmp(range_10, plot_file('12_00'))
+    assert filecmp.cmp(range_6, plot_file('12_01'))
+    # Plot 13 shows close-figs in action
+    assert filecmp.cmp(range_4, plot_file(13))
+    # Plot 14 has included source
+    with open(pjoin(html_dir, 'some_plots.html'), 'rb') as fobj:
+        html_contents = fobj.read()
+    assert b'# Only a comment' in html_contents
+    # check plot defined in external file.
+    assert filecmp.cmp(range_4, pjoin(html_dir, 'range4.png'))
+    assert filecmp.cmp(range_6, pjoin(html_dir, 'range6.png'))
+    # check if figure caption made it into html file
+    assert b'This is the caption for plot 15.' in html_contents

matPlotLib/env/lib/python3.7/site-packages/matplotlib/sphinxext/tests/tinypages/_static/README.txt

@@ -0,0 +1,7 @@
+##############################
+Static directory for tinypages
+##############################
+
+We need this README file to make sure the ``_static`` directory gets created
+in the installation.  The tests check for warnings in builds, and, when the
+``_static`` directory is absent, this raises a warning.

matPlotLib/env/lib/python3.7/site-packages/matplotlib/sphinxext/tests/tinypages/conf.py

@@ -0,0 +1,262 @@
+# tinypages documentation build configuration file, created by
+# sphinx-quickstart on Tue Mar 18 11:58:34 2014.
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys
+from os.path import join as pjoin, abspath
+import sphinx
+from distutils.version import LooseVersion
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.insert(0, os.path.abspath('.'))
+sys.path.insert(0, abspath(pjoin('..', '..')))
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = ['matplotlib.sphinxext.plot_directive']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = 'tinypages'
+copyright = '2014, Matplotlib developers'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '0.1'
+# The full version, including alpha/beta/rc tags.
+release = '0.1'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ['_build']
+
+# The reST default role (used for this markup: `text`) to use for all
+# documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+# If true, keep warnings as "system message" paragraphs in the built documents.
+#keep_warnings = False
+
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+if LooseVersion(sphinx.__version__) >= LooseVersion('1.3'):
+    html_theme = 'classic'
+else:
+    html_theme = 'default'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# Add any extra paths that contain custom files (such as robots.txt or
+# .htaccess) here, relative to this directory. These files are copied
+# directly to the root of the documentation.
+#html_extra_path = []
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'tinypagesdoc'
+
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+# The paper size ('letterpaper' or 'a4paper').
+#'papersize': 'letterpaper',
+
+# The font size ('10pt', '11pt' or '12pt').
+#'pointsize': '10pt',
+
+# Additional stuff for the LaTeX preamble.
+#'preamble': '',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+  ('index', 'tinypages.tex', 'tinypages Documentation',
+   'Matplotlib developers', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    ('index', 'tinypages', 'tinypages Documentation',
+     ['Matplotlib developers'], 1)
+]
+
+# If true, show URL addresses after external links.
+#man_show_urls = False
+
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+  ('index', 'tinypages', 'tinypages Documentation',
+   'Matplotlib developers', 'tinypages', 'One line description of project.',
+   'Miscellaneous'),
+]
+
+# Documents to append as an appendix to all manuals.
+#texinfo_appendices = []
+
+# If false, no module index is generated.
+#texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#texinfo_show_urls = 'footnote'
+
+# If true, do not generate a @detailmenu in the "Top" node's menu.
+#texinfo_no_detailmenu = False

matPlotLib/env/lib/python3.7/site-packages/matplotlib/sphinxext/tests/tinypages/index.rst

@@ -0,0 +1,21 @@
+.. tinypages documentation master file, created by
+   sphinx-quickstart on Tue Mar 18 11:58:34 2014.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to tinypages's documentation!
+=====================================
+
+Contents:
+
+.. toctree::
+    :maxdepth: 2
+
+    some_plots
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

matPlotLib/env/lib/python3.7/site-packages/matplotlib/sphinxext/tests/tinypages/range4.py

@@ -0,0 +1,5 @@
+from matplotlib import pyplot as plt
+
+plt.figure()
+plt.plot(range(4))
+plt.show()

matPlotLib/env/lib/python3.7/site-packages/matplotlib/sphinxext/tests/tinypages/range6.py

@@ -0,0 +1,13 @@
+from matplotlib import pyplot as plt
+
+
+def range4():
+    '''This is never be called if plot_directive works as expected.'''
+    raise NotImplementedError
+
+
+def range6():
+    '''This is the function that should be executed.'''
+    plt.figure()
+    plt.plot(range(6))
+    plt.show()

matPlotLib/env/lib/python3.7/site-packages/matplotlib/sphinxext/tests/tinypages/some_plots.rst

@@ -0,0 +1,129 @@
+##########
+Some plots
+##########
+
+Plot 1 does not use context:
+
+.. plot::
+
+    plt.plot(range(10))
+    a = 10
+
+Plot 2 doesn't use context either; has length 6:
+
+.. plot::
+
+    plt.plot(range(6))
+
+Plot 3 has length 4:
+
+.. plot::
+
+    plt.plot(range(4))
+
+Plot 4 shows that a new block with context does not see the variable defined
+in the no-context block:
+
+.. plot::
+    :context:
+
+    assert 'a' not in globals()
+
+Plot 5 defines ``a`` in a context block:
+
+.. plot::
+    :context:
+
+    plt.plot(range(6))
+    a = 10
+
+Plot 6 shows that a block with context sees the new variable.  It also uses
+``:nofigs:``:
+
+.. plot::
+    :context:
+    :nofigs:
+
+    assert a == 10
+    b = 4
+
+Plot 7 uses a variable previously defined in previous ``nofigs`` context. It
+also closes any previous figures to create a fresh figure:
+
+.. plot::
+    :context: close-figs
+
+    assert b == 4
+    plt.plot(range(b))
+
+Plot 8 shows that a non-context block still doesn't have ``a``:
+
+.. plot::
+    :nofigs:
+
+    assert 'a' not in globals()
+
+Plot 9 has a context block, and does have ``a``:
+
+.. plot::
+    :context:
+    :nofigs:
+
+    assert a == 10
+
+Plot 10 resets context, and ``a`` has gone again:
+
+.. plot::
+    :context: reset
+    :nofigs:
+
+    assert 'a' not in globals()
+    c = 10
+
+Plot 11 continues the context, we have the new value, but not the old:
+
+.. plot::
+    :context:
+
+    assert c == 10
+    assert 'a' not in globals()
+    plt.plot(range(c))
+
+Plot 12 opens a new figure.  By default the directive will plot both the first
+and the second figure:
+
+.. plot::
+    :context:
+
+    plt.figure()
+    plt.plot(range(6))
+
+Plot 13 shows ``close-figs`` in action.  ``close-figs`` closes all figures
+previous to this plot directive, so we get always plot the figure we create in
+the directive:
+
+.. plot::
+    :context: close-figs
+
+    plt.figure()
+    plt.plot(range(4))
+
+Plot 14 uses ``include-source``:
+
+.. plot::
+    :include-source:
+
+    # Only a comment
+
+Plot 15 uses an external file with the plot commands and a caption:
+
+.. plot:: range4.py
+
+   This is the caption for plot 15.
+
+
+Plot 16 uses a specific function in a file with plot commands:
+
+.. plot:: range6.py range6
+
+