Added support for passing through excluded kwargs so that custom parsers (like django) can be informed of implementation-specific attributes.

VERSION.txt

@@ -1 +1 @@
-6.8.2
+6.8.3

sandbox/cli.py

@@ -226,9 +226,7 @@ This command is used to parse configuration files and output the commands.
                 if args.docs == "html":
                     b = list()
                     b.append('<img src="%s"' % snippet.args[0])
-
-                    if snippet.caption:
-                        b.append('alt="%s"' % snippet.caption)
+                    b.append('alt="%s"' % snippet.caption or snippet.comment)
 
                     if snippet.classes:
                         b.append('class="%s"' % snippet.classes)
@@ -240,6 +238,7 @@ This command is used to parse configuration files and output the commands.
                         b.append('width="%s"' % snippet)
 
                     output.append(" ".join(b) + ">")
+                    output.append("")
                 elif args.docs == "plain":
                     output.append(snippet.args[0])
                     output.append("")
@@ -247,7 +246,7 @@ This command is used to parse configuration files and output the commands.
                     output.append(".. figure:: %s" % snippet.args[0])
 
                     if snippet.caption:
-                        output.append(indent(":alt: %s" % snippet.caption))
+                        output.append(indent(":alt: %s" % snippet.caption or snippet.comment))
 
                     if snippet.height:
                         output.append(indent(":height: %s" % snippet.height))
@@ -257,11 +256,7 @@ This command is used to parse configuration files and output the commands.
 
                     output.append("")
                 else:
-                    if snippet.caption:
-                        output.append("![%s](%s)" % (snippet.caption, snippet.args[0]))
-                    else:
-                        output.append("![](%s)" % (snippet.args[0]))
-
+                    output.append("![%s](%s)" % (snippet.caption or snippet.comment, snippet.args[0]))
                     output.append("")
             elif snippet.name == "template":
                 if args.docs == "plain":
@@ -306,8 +301,10 @@ This command is used to parse configuration files and output the commands.
     else:
         commands = list()
         for snippet in loader.get_snippets():
-            # Skip explanations and screenshots. They don't produce usable statements.
+            # Explanations and screenshots don't produce usable statements but may be added as comments.
             if snippet.name in ("explain", "screenshot"):
+                commands.append("# %s" % snippet.args[0])
+                commands.append("")
                 continue
 
             statement = snippet.get_statement()

scripttease/constants.py

@@ -1 +1,12 @@
+EXCLUDED_KWARGS = [
+    "cd",
+    "comment",
+    "environments",
+    "prefix",
+    "register",
+    "shell",
+    "stop",
+    "tags",
+]
+
 LOGGER_NAME = "script-tease"

scripttease/lib/loaders/base.py

@@ -6,6 +6,7 @@ from configparser import ParsingError, RawConfigParser
 from jinja2.exceptions import TemplateError, TemplateNotFound
 import logging
 import os
+from ...constants import EXCLUDED_KWARGS
 from ..contexts import Variable
 from ..snippets.mappings import MAPPINGS
 
@@ -114,7 +115,8 @@ def load_variables(path, env=None):
 class BaseLoader(File):
     """Base class for loading a command file."""
 
-    def __init__(self, path,  context=None, locations=None, mappings=None, profile="ubuntu", **kwargs):
+    def __init__(self, path,  context=None, excluded_kwargs=None, locations=None, mappings=None, profile="ubuntu",
+                 **kwargs):
         """Initialize the loader.
 
         :param path: The path to the command file.
@@ -124,6 +126,13 @@ class BaseLoader(File):
                         converted to a ``dict`` when passed to a Snippet or Template.
         :type context: scripttease.lib.contexts.Context
 
+        :param excluded_kwargs: For commands that support ad hoc sub-commands (like Django), this is a list of keyword
+                                argument names that must be removed. Defaults to the names of common command attributes.
+                                If your implementation requires custom but otherwise standard command attributes, you'll
+                                need to import the ``EXCLUDED_KWARGS`` constant and add your attribute names before
+                                passing it to the loader.
+        :type excluded_kwargs: list[str]
+
         :param locations: A list of paths where templates and other external files may be found. The ``templates/``
                           directory in which the command file exists is added automatically.
         :type locations: list[str]
@@ -140,6 +149,7 @@ class BaseLoader(File):
 
         """
         self.context = context
+        self.excluded_kwargs = excluded_kwargs or EXCLUDED_KWARGS
         self.is_loaded = False
         self.locations = locations or list()
         self.mappings = mappings or MAPPINGS
@@ -365,7 +375,7 @@ class Snippet(object):
 
     """
 
-    def __init__(self, name, args=None, content=None, context=None, kwargs=None, parser=None):
+    def __init__(self, name, args=None, content=None, context=None, excluded_kwargs=None, kwargs=None, parser=None):
         """Initialize a snippet.
 
         :param name: The canonical name of the snippet.
@@ -380,6 +390,9 @@ class Snippet(object):
         :param context: Additional context variables used to render the command.
         :type context: dict
 
+        :param excluded_kwargs: See parameter description for BaseLoader.
+        :type excluded_kwargs: list[str]
+
         :param kwargs: The keyword arguments found in the config file. These may be specific to the command or one of
                        the common options. They are accessible as dynamic attributes of the Snippet instance.
         :type kwargs: dict
@@ -389,6 +402,7 @@ class Snippet(object):
 
         """
         self.args = args or list()
+        self.excluded_kwargs = excluded_kwargs or EXCLUDED_KWARGS
         self.parser = parser
         self.content = content
         self.context = context or dict()
@@ -453,7 +467,7 @@ class Snippet(object):
                     args.append(arg.replace("$item", item))
 
                 if self.parser:
-                    statement = self.parser(self, args=args)
+                    statement = self.parser(self, args=args, excluded_kwargs=self.excluded_kwargs)
                 else:
                     statement = self._parse(args=args)
 
@@ -485,7 +499,7 @@ class Snippet(object):
             a.append("%s &&" % self.prefix)
 
         if self.parser:
-            statement = self.parser(self)
+            statement = self.parser(self, excluded_kwargs=self.excluded_kwargs)
         else:
             statement = self._parse()
 

scripttease/lib/snippets/django.py

@@ -1,20 +1,10 @@
 from commonkit import parse_jinja_string
+from ...constants import EXCLUDED_KWARGS
 
-DJANGO_EXCLUDED_KWARGS = [
-    "cd",
-    "comment",
-    "environments",
-    "prefix",
-    "register",
-    "shell",
-    "stop",
-    "tags",
-    # "venv", # ?
-]
 
 def django_command_parser(snippet, args=None, excluded_kwargs=None):
 
-    _excluded_kwargs = excluded_kwargs or DJANGO_EXCLUDED_KWARGS
+    _excluded_kwargs = excluded_kwargs or EXCLUDED_KWARGS
 
     # We need to remove the common options so any remaining keyword arguments are converted to switches for the
     # management command.

scripttease/version.py

@@ -2,4 +2,4 @@ DATE = "2021-01-26"
 VERSION = "6.8.2"
 MAJOR = 6
 MINOR = 8
-PATCH = 2
+PATCH = 3