Doc updates

Author: carl-adams-planet

src/planet_auth_config_injection/__init__.py

@@ -17,6 +17,34 @@
 
 This package provides interfaces and utilities for higher-level applications
 to inject configuration into the Planet Authentication Library.
+
+The Planet Auth Library provides configuration injection to improve the
+end-user experience of tools built on top of the Planet Auth Library.
+This allows built-in default client configurations to be provided.
+Namespacing may also be configured to avoid collisions in the Auth Library's
+use of environment variables.  Injected configration is primarily consumed
+by initialization functionality in planet_auth_utils.PlanetAuthFactory
+and the various planet_auth_utils provided `click` commands.
+
+These concerns belong more to the final end-user application than to a
+library that sits between the Planet Auth library and the end-user
+application, that itself may be used by a variety of applications in
+a variety of deployment environments
+
+Library writers may provide configuration injection to their developers,
+but should be conscious of the fact that multiple libraries within an
+application may depend on Planet Auth libraries.  Library writers are
+advised to provide configuration injection as an option for their users,
+and not silently force it into the loaded.
+
+In order to inject configuration, the application writer must do two things:
+
+1. They must write a class that implements the
+   [planet_auth_config_injection.BuiltinConfigurationProviderInterface][]
+   interface.
+2. They must set the environment variable `PL_AUTH_BUILTIN_CONFIG_PROVIDER` to the
+   fully qualified package, module, and class name of their implementation
+   _before_ any import of the `planet_auth` or `planet_auth_utils` packages.
 """
 
 from .builtins_provider import (

src/planet_auth_config_injection/builtins_provider.py

@@ -34,17 +34,11 @@
 
 class BuiltinConfigurationProviderInterface(ABC):
     """
-    Interface to define what profiles are built-in.
-
-    What auth configuration profiles are built-in is
-    completely pluggable for users of the planet_auth and
-    planet_auth_utils packages.  This is to support reuse
-    in different deployments, or even support reuse by a
-    different software stack all together.
-
-    To inject built-in that override the coded in defaults,
-    set the environment variable PL_AUTH_BUILTIN_CONFIG_PROVIDER
-    to the module.classname of a class that implements this interface.
+    Interface to define built-in application configuration.
+    This includes providing built-in auth client configuration
+    profiles, pre-defined trust environments for server use,
+    and namespacing for environment and global configuration
+    variables.
 
     Built-in profile names are expected to be all lowercase.
 

src/planet_auth_utils/commands/cli/main.py

@@ -84,7 +84,10 @@ def cmd_plauth_embedded(ctx):
     Embeddable version of the Planet Auth Client root command.
     The embedded command differs from the stand-alone command in that it
     expects the context to be instantiated and options to be handled by
-    the parent command.  See [planet_auth_utils.PlanetAuthFactory.initialize_auth_client_context][]
+    the parent command.  The [planet_auth.Auth][] library context _must_
+    be set to the object field `AUTH` in the click context object.
+
+    See [planet_auth_utils.PlanetAuthFactory.initialize_auth_client_context][]
     for user-friendly auth client context initialization.
 
     See [examples](/examples/#embedding-the-click-auth-command).