Describe shell and the directory ctx manager in more detail

Author: bittner

cli_test_helpers/commands.py

@@ -13,7 +13,14 @@ def shell(command, **kwargs):
     Execute a shell command capturing output and exit code.
 
     This is a better version of ``os.system()`` that captures output and
-    returns a convenient namespace object.
+    returns a convenient namespace object with 3 values:
+
+    ``exit_code``:
+        The command's exit code
+    ``stdout``:
+        The command's normal output
+    ``stderr``:
+        The command's error output
     """
     completed = run(command, shell=True, capture_output=True, check=False, **kwargs)
 

cli_test_helpers/decorators.py

@@ -72,6 +72,8 @@ class RandomDirectoryContext(LoggingIsolationMixin, TemporaryDirectory):
     """
     Change the execution directory to a random location, temporarily.
 
+    Use it to verify that your CLI application can operate from any
+    location, and is independent from your development directory tree.
     Keyword arguments are optional and identical to the ones of
     `tempfile.TemporaryDirectory`_ of the Python standard library.