diff --git a/VERSION.txt b/VERSION.txt index 295ec49..8fc3e14 100644 --- a/VERSION.txt +++ b/VERSION.txt @@ -1 +1 @@ -6.8.2 \ No newline at end of file +6.8.3 \ No newline at end of file diff --git a/sandbox/cli.py b/sandbox/cli.py index 23ad89a..960643b 100755 --- a/sandbox/cli.py +++ b/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('") + 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() diff --git a/scripttease/constants.py b/scripttease/constants.py index 26d0a12..ae45aae 100644 --- a/scripttease/constants.py +++ b/scripttease/constants.py @@ -1 +1,12 @@ +EXCLUDED_KWARGS = [ + "cd", + "comment", + "environments", + "prefix", + "register", + "shell", + "stop", + "tags", +] + LOGGER_NAME = "script-tease" diff --git a/scripttease/lib/loaders/base.py b/scripttease/lib/loaders/base.py index 96661b2..665a665 100644 --- a/scripttease/lib/loaders/base.py +++ b/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() diff --git a/scripttease/lib/snippets/django.py b/scripttease/lib/snippets/django.py index 21bf612..3d2ae8f 100644 --- a/scripttease/lib/snippets/django.py +++ b/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. diff --git a/scripttease/version.py b/scripttease/version.py index e8a2fdc..fef3ff8 100644 --- a/scripttease/version.py +++ b/scripttease/version.py @@ -2,4 +2,4 @@ DATE = "2021-01-26" VERSION = "6.8.2" MAJOR = 6 MINOR = 8 -PATCH = 2 +PATCH = 3