diff --git a/README.md b/README.md index 09a2dd8..9325b31 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,7 @@ of commands that we typically run to generate package artifacts (like migrations javascript). The deploy routine will be a collection of commands we typically run when deploying the site for the first time on a new server or when we deploy version updates on the server. -**Routines commands are run in the order they are registered, or by [priority](#priorities).** +**Routine commands are run in the order they are registered, or by [priority](#priorities).** In our settings file we may define these routines like this: diff --git a/django_routines/management/commands/routine.py b/django_routines/management/commands/routine.py index 1f2a5b9..6885c39 100644 --- a/django_routines/management/commands/routine.py +++ b/django_routines/management/commands/routine.py @@ -48,7 +48,16 @@ def {routine}( class Command(TyperCommand, rich_markup_mode="rich"): # type: ignore """ - A TyperCommand_ + A TyperCommand_ that reads the DJANGO_ROUTINES setting from settings and + builds out a set of subcommands for each routine that when invoked will run + those routines in order. Each routine also has a subcommand called ``list`` + that prints which commands will be executed and in what order given the + switches the user has selected. + + .. note:: + + If --verbosity is supplied, the value will be passed via options to any + command in the routine that accepts it. """ help = _("Run batches of commands configured in settings.") @@ -73,6 +82,10 @@ def routine(self, routine: t.Union[str, Routine]): @property def plan(self) -> t.List[RoutineCommand]: + """ + The RoutineCommands that make up the execution plan for the currently + active routine and switches. + """ assert self.routine return self.routine.plan(self.switches) @@ -85,6 +98,12 @@ def init(self, ctx: typer.Context, verbosity: Verbosity = verbosity): ) def _run_routine(self): + """ + Execute the current routine plan. If verbosity is zero, do not print the + commands as they are run. Also use the stdout/stderr streams and color + configurion of the routine command for each of the commands in the execution + plan. + """ assert self.routine for command in self.plan: if self.verbosity > 0: @@ -115,6 +134,10 @@ def _run_routine(self): raise CommandError(f"Command not found: {command.command_name}") def _list(self) -> None: + """ + List the commands that are part of the execution plan given the active + routine and switches. + """ for command in self.plan: priority = str(command.priority) cmd_str = command.command_str diff --git a/doc/source/index.rst b/doc/source/index.rst index db9a1ee..241109a 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -19,7 +19,7 @@ the site for the first time on a new server or when we deploy version updates on .. note:: - Routines commands are run in the order they are registered, or by priority_. + Routine commands are run in the order they are registered, or by priority_. .. literalinclude:: ../../examples/readme.py :caption: settings.py