doc improvements (#21)

* Prefer "paramters" over "args" for function documentation.

* working on improving the docs

* change stats badge

* split up the API docs into two pages.

* fix broken link to readthedocs

* link checkers for docs

* reorder secetions

* link to multiple sources of download stats

* adjust nav

* improve CLI example

* small fixes

Author: carl-adams-planet

.github/workflows/release-build.yml

@@ -57,6 +57,9 @@ jobs:
   #     - name: "Nox: MKDocs Build"
   #       run: |
   #         nox -s mkdocs_build
+  #     - name: "Nox: MKDocs Check Links"
+  #       run: |
+  #         nox -s mkdocs_checklinks
   #     - name: "Save Artifacts - MkDocs"
   #       uses: actions/upload-artifact@v4
   #       with:

.github/workflows/test.yml

@@ -173,3 +173,8 @@ jobs:
       - name: 'Nox: MKDocs Build'
         run: |
           nox -s mkdocs_build
+          # Not checking the links in the pipeline right now.
+          # This is throwing some false positives on intra-md links
+          # that build OK, and would also be caught by our mkdocs
+          # strict mode setting.
+          # nox -s mkdocs_checklinks

README.md

@@ -1,7 +1,8 @@
 # Planet Auth Utility Library
 [![Build Status](https://github.com/planetlabs/planet-auth-python/actions/workflows/test.yml/badge.svg)](https://github.com/planetlabs/planet-auth-python/actions/workflows/test.yml)
-[![PyPI Downloads](https://static.pepy.tech/badge/planet-auth)](https://pepy.tech/projects/planet-auth)
 [![Read The Docs](https://app.readthedocs.org/projects/planet-auth/badge/)](https://planet-auth.readthedocs.io/)
+[![PyPI Downloads (pypistats.org)](https://img.shields.io/pypi/dm/planet-auth)](https://pypistats.org/packages/planet-auth)
+[![PyPI Downloads (peppy.tech)](https://static.pepy.tech/badge/planet-auth)](https://pepy.tech/projects/planet-auth)
 
 The Planet Auth Library provides generic authentication utilities for clients
 and for services.  For clients, it provides means to obtain access tokens that

docs/api-planet-auth-utils.md

@@ -0,0 +1,6 @@
+# ::: planet_auth_utils
+    options:
+      show_root_full_path: true
+      inherited_members: true
+      show_submodules: true
+      show_if_no_docstring: false

docs/api-planet-auth.md

@@ -0,0 +1,6 @@
+# ::: planet_auth
+    options:
+      show_root_full_path: true
+      inherited_members: true
+      show_submodules: true
+      show_if_no_docstring: false

docs/api.md

@@ -0,0 +1,4 @@
+# Built-in Auth Client Profile Injection
+
+TODO: Document how applications may inject built-in auth client profiles for
+a smoother application user and developer experience.

docs/built-ins.md

@@ -1,9 +1,9 @@
 # Changelog
 
-## 2.1.0 - 2025 TBD
+## 2.1.0 - 2025-??-??
 - Initial public release targeting integration with the
   [Planet Client for Python](https://github.com/planetlabs/planet-client-python).
 
-## [Unreleased: 2.0.*] - YYYY-MM-DD
+## [Unreleased: 2.0.*]
 - All releases in the 2.0.X series are development releases, even if not
   tagged as such. This work included some shakedowns of the release pipelines.

docs/changelog.md

@@ -9,40 +9,13 @@ AuthClient Configuration dictionaries may either be provided directly, or loaded
 from disk when saved in a `Profile` (See below).
 
 While it is possible to work directly with the lower level implementation
-classes, it is generally simpler to use the higher level management code in
-[planet_auth.Auth][], or the factory methods in [planet_auth.AuthClient][] 
-and [planet_auth.AuthClientConfig][] to configure and instantiate instances.
-Directly using the lower level implementations should not be necessary in
-most cases.
+classes, it is generally simpler to organize the working set of objects
+with an [Auth Context][planet_auth.Auth] instance created from one of the
+factory methods in [planet_auth_utils.PlanetAuthFactory][]
 
 A number of auth client implementations are provided.  Clients should
 select the one most appropriate for their use case.
 
-### Planet Legacy Client
-Implemented by [planet_auth.PlanetLegacyAuthClient][] and [planet_auth.PlanetLegacyAuthClientConfig][]
-
-Configuration:
-```json linenums="1" title="~/.planet/_profile_name_/auth_client.json"
-{% include 'auth-client-config/planet-legacy.json' %}
-```
-
-Profile Usage:
-```python linenums="1"
-from planet_auth import Auth
-
-auth_ctx = Auth.initialize_from_profile(profile="_profile_name_")
-```
-
-
-Direct Usage:
-```python linenums="1"
-from planet_auth import Auth
-auth_ctx = Auth.initialize_from_config_dict(
-    client_config={ ... content of auth_client.json ... },
-    token_file="/my_token_file.json"
-)
-```
-
 ### OAuth Clients
 #### Auth Code with PKCE
 Implemented by [planet_auth.AuthCodeAuthClient][] and [planet_auth.AuthCodeClientConfig][]
@@ -54,18 +27,16 @@ Configuration:
 
 Profile Usage:
 ```python linenums="1"
+{% include 'snippets/auth-client-context-from-saved-profile.py' %}
+
 from planet_auth import Auth
 
 auth_ctx = Auth.initialize_from_profile(profile="_profile_name_")
 ```
 
 Direct Usage:
 ```python linenums="1"
-from planet_auth import Auth
-auth_ctx = Auth.initialize_from_config_dict(
-    client_config={ ... content of auth_client.json ... },
-    token_file="/my_token_file.json"
-)
+{% include 'snippets/auth-client-context-oauth-direct.py' %}
 ```
 
 #### Auth Code with PKCE and Client Public Key
@@ -164,6 +135,25 @@ outbound calls, which is one of the primary aims of most auth client types.
 Instead, this client configuration can only be used to validate incoming
 tokens.
 
+### Planet Legacy Client
+Implemented by [planet_auth.PlanetLegacyAuthClient][] and [planet_auth.PlanetLegacyAuthClientConfig][]
+
+Configuration:
+```json linenums="1" title="~/.planet/_profile_name_/auth_client.json"
+{% include 'auth-client-config/planet-legacy.json' %}
+```
+
+Profile Usage:
+```python linenums="1"
+{% include 'snippets/auth-client-context-from-saved-profile.py' %}
+```
+
+
+Direct Usage:
+```python linenums="1"
+{% include 'snippets/auth-client-context-pl-legacy-direct.py' %}
+```
+
 ## Environment Variables
 See [planet_auth_utils.EnvironmentVariables][] for a list of environment variables.
 

docs/configuration.md

@@ -0,0 +1,31 @@
+# CLI Examples
+
+## Embedding the `plauth` Command in Another `click` Program
+It is possible to embed the [`plauth`](./cli-plauth.md) command into other programs to
+present a unified experience that leverages the _Planet Auth Library_
+package for client authentication plumbing.  This is done by using
+a special version of the command that is configured for embedding.
+
+When using the embedded version of the command, the outer application
+must take on the responsibility of instantiating the auth context and
+handling command line options so that this context may be available
+to click commands that are outside the `plauth` root command.
+
+```python linenums="1"
+{% include 'cli/embed-plauth-click.py' %}
+```
+
+## Advanced Embedding
+Beyond simple embedding, it is possible for an application to customize some
+the appearance and behavior of the command.
+
+For example, an application may rename commands or hide options and sub-commands
+it does not wish to expose to the user.  For an extensive example of this in a
+downstream application, you can look at the
+[Planet SDK](https://github.com/planetlabs/planet-client-python)'s
+CLI program, which both embeds the whole `plauth` command as a hidden
+root level sub-command [`planet plauth`](https://github.com/planetlabs/planet-client-python/blob/main/planet/cli/cli.py),
+and cherry-picks specific sub-commands to power its own
+[`auth`](https://github.com/planetlabs/planet-client-python/blob/main/planet/cli/auth.py)
+sub-command.  This allows the downstream application to leverage the _Planet Auth Library_,
+while also using [configuration injection](./built-ins.md) to provide a smoother end-user experience

docs/examples-cli.md

@@ -0,0 +1,73 @@
+# Client Examples
+Client examples cover scenarios in which a program wishes to use
+the planet auth utilities as a client, obtaining credentials
+from authentication services so that they may be used to
+make authenticated requests to other network services.
+
+## OAuth Client Authentication
+A custom auth client profile may be used to configure the AuthClient
+to use an arbitrary OAuth2 auth service to obtain access tokens for
+use with application APIs.
+See [Configuration and Profiles](./configuration.md) for more information
+on client types and profiles.
+
+1. Create a `~/.planet/<profile_name>/auth_client.json` or `~/.planet/<profile_name>/auth_client.sops.json` file.
+For example, to create a custom profile named "my-custom-profile", create the following:
+```json linenums="1" title="~/.planet/my-custom-profile/auth_client.json"
+{% include 'auth-client-config/oauth-auth-code-grant-public-client.json' %}
+```
+2. Initialize the client library with the specified profile.  Note: if the environment variable
+`PL_AUTH_PROFILE` is set, it will be detected automatically by [planet_auth_utils.PlanetAuthFactory][],
+and it will not be necessary to explicitly pass in the profile name:
+```python linenums="1"
+{% include 'auth-client/oauth/initialize-client-lib-on-disk-profile.py' %}
+```
+An alternative to creating a file on disk is to initialize_from_profile a client
+purely in memory.  For some runtime environments where local storage may
+not be available or trusted, this may be more appropriate:
+```python linenums="1"
+{% include 'auth-client/oauth/initialize-client-lib-in-memory.py' %}
+```
+3. Perform initial login to obtain and save long term credentials, if required
+by the configured profile.  An initial login is usually required for auth
+clients that act on behalf of a user and need to perform an interactive login.
+Clients configured for service operation may frequently skip this step:
+```python linenums="1"
+{% include 'auth-client/oauth/perform-oauth-initial-login.py' %}
+```
+4. Make authenticated requests:
+    * Option 1 - Using `requests`:
+```python linenums="1"
+{% include 'auth-client/oauth/make-oauth-authenticated-requests-request.py' %}
+```
+    * Option 2 - Using `httpx`:
+```python linenums="1"
+{% include 'auth-client/oauth/make-oauth-authenticated-httpx-request.py' %}
+```
+
+## Performing a Device Login
+The procedure for performing initial user login on a UI limited device
+is slightly different.  Rather than simply calling `login()`, it is necessary
+to initiate the process with a call to `device_login_initiate()`, display the
+returned information to the user so that the user may authorize the client
+asynchronously, and complete the process by calling `device_login_complete()`.
+This procedure only applies to clients that are permitted to use the
+Device Authorization OAuth flow.
+
+```python linenums="1"
+{% include 'auth-client/oauth/perform-oauth-device-login.py' %}
+```
+
+## Planet Legacy Authentication
+The proprietary Planet legacy authentication protocol is targeted for future
+deprecation.  It should not be used for any new development.
+
+### Initial Login
+```python linenums="1"
+{% include 'auth-client/planet-legacy/perform-legacy-initial-login.py' %}
+```
+
+### Authenticated `requests` Call
+```python linenums="1"
+{% include 'auth-client/planet-legacy/make-legacy-authenticated-requests-request.py' %}
+```

docs/examples-client.md

@@ -0,0 +1,7 @@
+# Installation
+
+## Install from _PyPI.org_ using `pip`
+Install the required modules:
+```shell
+pip install planet-auth
+```

docs/examples-installation.md

@@ -0,0 +1,50 @@
+# Service Examples
+Service examples cover scenarios in which a program wishes to use
+the planet auth utilities as a service, verifying the authenticity
+of access credentials presented to the service by a client.
+
+It should be noted that Services may also act as clients when making
+calls to other services.  When a service is acting in such a capacity,
+the [Client Examples](./examples-client.md) apply.
+When the service is acting on behalf of itself, it is likely that
+a [OAuth2 Client Credentials](./configuration.md#client-credentials-with-client-secret)
+configuration applies.
+
+When a service is acting on behalf of one of its clients... 
+(TODO: cover this.)
+
+## Verifying OAuth Clients
+The [planet_auth.OidcMultiIssuerValidator][] class is provided to assist with
+common OAuth client authentication scenarios.  This class can be configured
+with a single authority for normal operations, and may optionally be configured
+with a secondary authorities.  This allows for complex deployments such as
+the seamless migration between auth servers over time.
+
+This utility class may be configured for entirely local token validation,
+or may be configured to check token validity against the OAuth token inspection
+endpoint.  For most operations, local validation is expected to be used, as
+it is more performant, not needing to make blocking network calls, and more
+robust, not depending on external service availability.  For high value operations,
+remote validation may be performed which checks whether the specific access
+token has been revoked.
+
+Tokens are normally not long-lived. Token lifespans should be selected to
+strike a balance between security concerns and allow frequent use of local
+validation, and not overburden the token inspection endpoint.
+
+Checking tokens against the OAuth token inspection endpoint does require the
+use of OAuth clients that are authorized to use the endpoint, and may not
+be available to anonymous clients, depending on the auth server configuration.
+
+### Local Access Token Validation
+```python linenums="1" title="Basic usage of OidcMultiIssuerValidator. Validate access tokens locally."
+{% include 'service/flask--oidc-multi-issuer--local-only-validation.py' %}
+```
+
+### Local and Remote Access Token Validation
+```python linenums="1" title="Advanced usage of OidcMultiIssuerValidator. Validate access tokens against OAuth inspection endpoints using custom auth clients."
+{% include 'service/flask--oidc-multi-issuer--local-and-remote-validation.py' %}
+```
+
+## Verifying Planet Legacy Client
+This is not supported by this library.