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