From 5a1f9e044acfdc6e053655c598a10853a6a580ca Mon Sep 17 00:00:00 2001
From: Glen Whitney <glen@studioinfinity.org>
Date: Wed, 13 Jan 2021 21:36:29 -0800
Subject: [PATCH] refactor: Adjust to latest commit of simple plugin

  Now reiterates significantly less code from the simple plugin. Also, adjusted
  the default for extract_standard_markdown when copy_standard_markdown is true.
---
 mkdocs_semiliterate/plugin.py | 97 ++++++++++++++---------------------
 setup.cfg                     |  2 +-
 tests/sites.bash              |  2 +-
 3 files changed, 41 insertions(+), 60 deletions(-)

diff --git a/mkdocs_semiliterate/plugin.py b/mkdocs_semiliterate/plugin.py
index a11636e..78a9bbc 100644
--- a/mkdocs_semiliterate/plugin.py
+++ b/mkdocs_semiliterate/plugin.py
@@ -12,7 +12,7 @@ of the `simple` plugin.)
 
 from mkdocs import utils
 from mkdocs.config import config_options
-from mkdocs_simple_plugin.plugin import SimplePlugin, StreamExtract, LazyFile
+from mkdocs_simple_plugin.plugin import SimplePlugin, StreamExtract
 
 import re
 import yaml
@@ -62,17 +62,14 @@ parameters makes it easier to extract "front-matter" style documentation from
 files. It also means that a plain `{! file.md !}` directive will simply
 incorporate the full contents of `file.md`.
         """
-        self.start_hot = False
+        start_hot = False
         if 'start' not in kwargs:
             kwargs['start'] = 'dummy'
-            self.start_hot = True
+            start_hot = True
         super().__init__(input_stream, output_stream, **kwargs)
-
-    def extract(self):
-        if self.start_hot:
+        if start_hot:
             self.extracting = True
             self.start = False
-        super().extract()
 
     include_open = re.compile(r'''(?<![`\\])(\{\!\s*)([\s'"])''')
     include_quoted_file = re.compile(
@@ -107,7 +104,15 @@ incorporate the full contents of `file.md`.
             raise EOFError(errmsg)
         include_path = self.include_root + '/' + body_match['fn']
         new_root = re.match(r'(.*)/', include_path)[1]
-        include_parameters = yaml.safe_load(body_match['yml'])
+        try:
+            include_parameters = yaml.safe_load(body_match['yml'])
+        except Exception as err:
+            newmsg = (f"While attempting to include '{include_path}', could"
+                      + f" not parse yaml '{body_match['yml']}'.")
+            if hasattr(err, 'message'):
+                raise SyntaxError(
+                    f"{newmsg} YAML parser reports: {err.message}")
+            raise SyntaxError(f"{newmsg} Caught exception: {str(err)}")
         if not include_parameters:
             include_parameters = {}
         with open(include_path) as include_file:
@@ -115,13 +120,18 @@ incorporate the full contents of `file.md`.
             inclusion = StreamInclusion(
                 include_file, self.output_stream, include_root=new_root,
                 **include_parameters)
-            if inclusion.productive():
+            if inclusion.extract():
                 self.wrote_something = True
         self.transcribe(remainder[body_match.end():])
 
 
 class SemiliteratePlugin(SimplePlugin):
     r""" md   An extension of the mkdocs-simple-plugin
+
+In addition, block-comment markdown `/** md` ... `**/` is by
+default scanned for in all files with an extension, as it's valid in so many
+disparate languages.
+
 ### Additional plugin parameters
 
 `semiliterate` adds a couple of new plugin parameters to further tailor its
@@ -129,7 +139,7 @@ behavior as compared to `simple`. They are described in this section, with
 default values in parentheses at the beginning of each entry.
 
 {! plugin.py ---
-  start: '[*]SimplePlugin.config_scheme'
+  start: '[*]altered_config_scheme'
   terminate: '^\s*\)'
   replace:
   - ["\\('(.*)',\\s*$", '\1\n']
@@ -138,9 +148,16 @@ default values in parentheses at the beginning of each entry.
 !}
     """
 
+    super_sdict = dict(SimplePlugin.config_scheme)
+    super_semi_dflt = super_sdict['semiliterate'].default
+    semi_dflt = [b if r'\*' not in b['stop'] else dict(b, pattern=r'\.')
+                 for b in super_semi_dflt]
+    altered_config_scheme = dict(
+        super_sdict,
+        semiliterate=config_options.Type(list, default=semi_dflt)).items()
     config_scheme = (
         # Note documentation of each new parameter **follows** the parameter.
-        *SimplePlugin.config_scheme,
+        *altered_config_scheme,
         ('copy_standard_markdown',
          config_options.Type(bool, default=False)),
         # Whether to add MkDocs' list of standard Markdown extensions to the
@@ -152,15 +169,16 @@ default values in parentheses at the beginning of each entry.
         ('extract_standard_markdown',
          config_options.Type(dict, default={})),
         # If the `enable` key of this dict parameter is true
-        #    (which it defaults to),
+        #    (it defaults to the opposite of `copy_standard_markdown`),
         #    it adds a semiliterate block causing extraction (and hence
         #    include-directive processing) from all standard Markdown files
         #    (as defined by MkDocs). The remaining keys of this parameter are
         #    included as parameters of that semiliterate block. Thus, the
-        #    default value of the parameter arranges for Markdown file to be
+        #    default values of the parameters arrange for Markdown files to be
         #    copied "as-is", except possibly for embedded inclusions.
-        #    On the other hand, setting it to `{enable: false}` will prevent
-        #    automatic extraction from standard Markdown files.
+        #    On the other hand, setting this parameter to `{enable: false}`
+        #    (which is also the default when `copy_standard_markdown` is true)
+        #    will prevent automatic extraction from standard Markdown files.
         ('report_docs_build',
          config_options.Type(bool, default=False))
         # If true, the name of the temporary directory to which generated docs
@@ -172,9 +190,11 @@ default values in parentheses at the beginning of each entry.
         if self.config['report_docs_build']:
             utils.log.info(
                 f"semiliterate: generating docs in {self.build_docs_dir}")
+        dflt_enable = False
         if not self.config['copy_standard_markdown']:
             self.include_extensions = self.config['include_extensions']
-        if self.config['extract_standard_markdown'].get('enable', True):
+            dflt_enable = True
+        if self.config['extract_standard_markdown'].get('enable', dflt_enable):
             ext_pat = '|'.join(re.escape(s) for s in utils.markdown_extensions)
             self.semiliterate.append(dict(
                 pattern=re.compile(f"^(.*(?:{ext_pat}))$"),
@@ -182,46 +202,7 @@ default values in parentheses at the beginning of each entry.
                 **self.config['extract_standard_markdown']))
         return super().build_docs()
 
-    # FIXME: This method is copied from simple, just to insert a control
-    # over what class is used to do the extraction. Try to get this inserted as
-    # the method of the same name in simple.
-    def extract_from(self, from_directory, name, destination_directory):
-        """Extract content from the file in _from_directory_ named _name_
-           to a file or files in _destination_directory_, as specified by
-           the semiliterate parameters.
-        """
-        new_paths = []
-        original = "{}/{}".format(from_directory, name)
-        for item in self.semiliterate:
-            name_match = item['pattern'].search(name)
-            if name_match:
-                new_name = ''
-                if name_match.lastindex:
-                    new_name = (name[:name_match.start(name_match.lastindex)]
-                                + '.md'
-                                + name[name_match.end(name_match.lastindex):])
-                if 'destination' in item:
-                    new_name = name_match.expand(item['destination'])
-                if not new_name:
-                    raise LookupError(
-                        "mkdocs-simple-plugin: No last group in match of"
-                        + "{} to {} and no destination".format(
-                            item['pattern'], name))
-                new_file = LazyFile(destination_directory, new_name)
-                with open(original) as original_file:
-                    utils.log.debug(
-                        "mkdocs-simple-plugin: Scanning {}...".format(original))
-                    productive = self.try_extraction(
-                        original_file, from_directory, new_file, **item)
-                    new_file.close()
-                    if productive:
-                        new_path = "{}/{}".format(destination_directory,
-                                                  new_name)
-                        utils.log.debug(
-                            "        ... extracted {}".format(new_path))
-                        new_paths.append((original, new_path))
-        return new_paths
-
     def try_extraction(self, original_file, root, new_file, **kwargs):
-        return StreamInclusion(
-            original_file, new_file, include_root=root, **kwargs).productive()
+        extraction = StreamInclusion(
+            original_file, new_file, include_root=root, **kwargs)
+        return extraction.extract()
diff --git a/setup.cfg b/setup.cfg
index eb987fd..22926a2 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -1,6 +1,6 @@
 [metadata]
 name = mkdocs-semiliterate
-version = 0.0.9
+version = 0.0.10
 
 [options]
 packages = mkdocs_semiliterate
diff --git a/tests/sites.bash b/tests/sites.bash
index 17649b3..cecff55 100644
--- a/tests/sites.bash
+++ b/tests/sites.bash
@@ -3,7 +3,7 @@ startdir=$PWD
 for file in tests/fixtures/*
 do
     cd "$startdir/$file"
-    mkdocs build
+    mkdocs -v build
     # unfortunately MkDocs writes the run date in the last few lines of index:
     head -n -3 site/index.html > site/croppedindex.html
     rm site/index.html