documentation updates

Author: bckohan

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:
 

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

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