mkdocs_semiliterate/plugin.py

@@ -112,6 +112,47 @@ is checked for `{! ... !}`.
             raise EOFError(errmsg)
         filename = body_match['fn']
         gitextract = False
+        dq_doc = """ md
+### Double-quoted filenames and Git extraction
+
+Standard Python escape sequences in double-quoted filenames are interpreted
+as usual; for example you can write
+```
+{! ../tests/fixtures/quoted-filename/README.md extract:
+  start: '(.*!.*)'
+  stop: '\s'
+!}
+```
+to include a file whose name (`snippet/Say "Don't"`, in this case) has both
+double and single quotes.
+
+Further, `semiliterate` supports a special escape to extract a file from the
+Git archive of the project (presuming it is under Git version control) and then
+include content from that file. For example, you could write
+```
+{! ../tests/fixtures/git-inclusion/README.md extract:
+  start: '(.*!.*)'
+  stop: '\s'
+!}
+```
+
+to extract content starting after the `### install` line from the
+`mkdocs.yml` file in the Git commit of this repository
+tagged `0.1.0`. This feature is primarily useful if you are documenting the
+development or changes to a project over time, and want to be sure that
+material included in your documentation does _not_ change as the project
+progresses. (This behavior is as opposed to the usual case, in which you want
+your documentation to incorporate the most up-to-date version of extracted
+content.)
+
+The precise behavior for a FILENAME argument in a `{! ... !}` inclusion of the
+form
+
+`"\git SPECIFIER"`
+
+is that the output of `git show SPECIFIER` is written to a temporary file,
+and that file is extracted from.
+"""
         if doublequoted:
             if filename[:5] == r'\git ':
                 gitextract = True
@@ -151,10 +192,23 @@ is checked for `{! ... !}`.
 class SemiliteratePlugin(SimplePlugin):
     r""" md   An extension of the mkdocs-simple-plugin
 
-In addition, block-comment markdown `/** md` ... `**/` is by
+### Universal block-comment markdown
-default scanned for in all files with _any_ extension, as it's valid in so many
-disparate languages.
 
+By default, `semiliterate` scans for block-comment markdown `/** md` ... `**/`
+in all files with _any_ extension, as it's valid in so many disparate languages.
+(As opposed to `simple`, which defaults to searching for such markdown in a
+specific list of file types.)
+    """
+
+    super_sdict = dict(SimplePlugin.config_scheme)
+    super_semi_dflt = super_sdict['semiliterate'].default
+    semi_dflt = [b if 'js' not in b['pattern'] 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()
+
+    add_param_doc = r""" md
 ### Additional plugin parameters
 
 `semiliterate` adds a couple of new plugin parameters to further tailor its
@@ -170,14 +224,6 @@ default values in parentheses at the beginning of each entry.
 terminate: '^\s*\)'
 !}
     """
-
-    super_sdict = dict(SimplePlugin.config_scheme)
-    super_semi_dflt = super_sdict['semiliterate'].default
-    semi_dflt = [b if 'js' not in b['pattern'] 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.
         *altered_config_scheme,

setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = mkdocs-semiliterate
-version = 0.1.1
+version = 0.2.0
 description = Extension of mkdocs-simple-plugin adding easy content inclusion
 long_description = file: README.md
 long_description_content_type = text/markdown