Merge branch 'main' into carl/initial-drop-from-internal--docs

carl-adams-planet · carl-adams-planet · commit 7eddd8195f6c · 2024-12-19T18:33:48.000-08:00
diff --git a/.github/workflows/release-build.yml b/.github/workflows/release-build.yml
@@ -43,25 +43,28 @@ jobs:
           name: planet-auth-src-targz
           path: dist/planet_auth*.tar.gz
 
-  build-docs:
-    name: "Build Documentation Packages"
-    runs-on: ubuntu-latest
-    steps:
-      - name: "Checkout code"
-        uses: actions/checkout@v4
-      - name: Prepare common Python build environment
-        uses: ./.github/actions/python-build-env-setup
-        with:
-          python-version: ${{ env.PYTHON_VERSION }}
-      # - name: "Pull Build Number"
-      #   uses: ./.github/actions/version-dot-buildnum-fetch
-      #   with:
-      #     version-file: version-with-buildnum.txt
-      - name: "Nox: MKDocs Build"
-        run: |
-          nox -s mkdocs_build
-      - name: "Save Artifacts - MkDocs"
-        uses: actions/upload-artifact@v4
-        with:
-          name: planet-auth-mkdocs-site
-          path: site/**
+  # Not building this as a release artifact at this time.
+  # Docs are published to ReadTheDocs through other mechanisms.
+  #
+  # build-docs:
+  #   name: "Build Documentation Packages"
+  #   runs-on: ubuntu-latest
+  #   steps:
+  #     - name: "Checkout code"
+  #       uses: actions/checkout@v4
+  #     - name: Prepare common Python build environment
+  #       uses: ./.github/actions/python-build-env-setup
+  #       with:
+  #         python-version: ${{ env.PYTHON_VERSION }}
+  #     # - name: "Pull Build Number"
+  #     #   uses: ./.github/actions/version-dot-buildnum-fetch
+  #     #   with:
+  #     #     version-file: version-with-buildnum.txt
+  #     - name: "Nox: MKDocs Build"
+  #       run: |
+  #         nox -s mkdocs_build
+  #     - name: "Save Artifacts - MkDocs"
+  #       uses: actions/upload-artifact@v4
+  #       with:
+  #         name: planet-auth-mkdocs-site
+  #         path: site/**
diff --git a/.github/workflows/release-orchestrate.yml b/.github/workflows/release-orchestrate.yml
@@ -4,10 +4,7 @@ permissions:
   actions: read
   contents: read
 
-# TODO: insure we can only release from privileged branches/tags?
-
 on:
-  # push:  # Just for testing  FIXME: Remove this.
   workflow_dispatch:
     inputs:
       build-variant:
diff --git a/.github/workflows/release-publish.yml b/.github/workflows/release-publish.yml
@@ -21,35 +21,8 @@ env:
   PYTHON_VERSION: "3.13"
 
 jobs:
-  # release-checkpoint:
-  #   name: "Final Release Checkpoint"
-  #   runs-on: ubuntu-latest
-  #   permissions:
-  #     actions: read
-  #     contents: write
-  #   # TODO: Gate actual prod deployment on a manual approval to bonk.
-  #   steps:
-  #     # - name: "Checkout code"
-  #     #   uses: actions/checkout@v4
-  #     # - name: "Prepare common Python build environment"
-  #     #   uses: ./.github/actions/python-build-env-setup
-  #     #   with:
-  #     #     python-version: ${{ env.PYTHON_VERSION }}
-  #     - name: "Record Release Tag"
-  #       # While we drop tags at the beginning of the release pipeline, we also record
-  #       # that we published the release here at the end of the release pipeline.
-  #       # Tests could fail, and this should record that difference between attempting
-  #       # a release, and publishing a release.
-  #       run: |
-  #         set -x
-  #         git config --global user.email "planet-auth-python-github-cicd@planet.com"
-  #         git config --global user.name  "CICD for github repository ${GITHUB_REPOSITORY}"
-  #         git tag -a -m "test tag comment" "release-${{inputs.version-with-buildnumber}}"
-  #         git push origin                  "release-${{inputs.version-with-buildnumber}}"
-
   release-pypi-test:
     name: "Release package to PyPi (Test)"
-    # needs: release-checkpoint
     runs-on: ubuntu-latest
     # environment: staging
     steps:
@@ -85,7 +58,6 @@ jobs:
 
   release-pypi-production:
     name: "Release package to PyPi (Production)"
-    # needs: release-checkpoint
     runs-on: ubuntu-latest
     # environment: staging
     steps:
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1 @@
+TODO: document submitting tickets and PRs.  We will likely lean on the SDK process.
diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
@@ -0,0 +1,28 @@
+# Development
+
+## Development Tools
+All packages needed for different facets of development are specified as
+"extra" packages.  Each of these may be installed using `pip`.  For example,
+the following would install the extra packages needed for the operation of
+the code samples in the documentation:
+
+```console
+pip install planet-auth[examples]
+```
+
+The following extra packages have been defined:
+* `build` - Packages needed to build distribution packages.
+* `docs` - Packages needed to build the documentation.
+* `test` - Packages needed to run all the test and linting suites.
+* `examples` - Packages needed by example code.
+* `dev` - Meta package that combines `build`, `docs`, and `test`.
+
+## Nox
+[Nox](https://nox.thea.codes/) is the preferred mechanism for performing all
+common development activities.  This includes running unit tests, linting,
+code formatting, and static analysis.
+
+For a complete list of supported activities, list nox sessions.:
+```console
+nox -l
+```
diff --git a/README.md b/README.md
@@ -0,0 +1,36 @@
+# Planet Auth Utility Library
+
+The Planet Auth Library provides generic authentication utilities for clients
+and for services.  For clients, it provides means to obtain access tokens that
+can be used to access network services.  For services, it provides tools to
+validate the same access tokens.
+
+The [Planet SDK for Python](https://developers.planet.com/docs/pythonclient/)
+leverages this library, and is pre-configured for the Planet Cloud Service used
+by customers.
+
+## Installation and Quick Start
+
+The Planet Auth Library for Python is [hosted on PyPI](https://pypi.org/project/planet-auth/)
+and can be installed via:
+
+```console
+pip install planet-auth
+```
+
+To install from source, first clone this repository, then navigate to the
+root directory (where [`pyproject.toml`](./pyproject.toml) lives) and run:
+
+```console
+pip install .
+```
+
+## Using the Planet Auth Library
+See the developer documentation at [Planet Auth on Read The Docs](TBD).
+
+## Development
+See [DEVELOPMENT](./DEVELOPMENT.md) for details on library development.
+
+## Releasing
+
+The release process is outlined in [RELEASE](RELEASE.md).
diff --git a/docs/changelog.md b/docs/changelog.md
@@ -4,4 +4,4 @@
 - 2.X is the initial public release of Planet auth libraries, targeting integration
   with our public Python SDK [`planet-client-python`](https://github.com/planetlabs/planet-client-python)/
 - 2.0.X is a development series, not intended for production. When ready,
-  the version will be bumped beyond 2.1.
+  the version will be bumped to 2.1.
diff --git a/docs/index.md b/docs/index.md
@@ -1,11 +1,23 @@
-# Planet Auth
+# Planet Auth Utility Library
 
-## Overview
+The Planet Auth Library provides generic authentication utilities for clients
+and for services.  For clients, it provides means to obtain access tokens that
+can be used to access network services.  For services, it provides tools to
+validate the same access tokens.
 
-Planet auth utility code.
+The architecture of the code was driven by OAuth2, but is intended to be easily
+extensible to new authentication protocols in the future.  Since both clients
+and resource servers are both themselves clients to authorization servers in
+an OAuth2 deployment, this combining of resource client and resource server
+concerns in a single library was seen as natural.
 
-The code in this library is general auth utility code, and does not make
-any assumptions about the environment in which it is operating.  The
-[Planet SDK for Python](https://developers.planet.com/docs/pythonclient/)
+Currently, this library supports OAuth2, Planet's legacy proprietary
+authentication protocols, and static API keys.
+
+This library does not make any assumptions about the specific environment in which
+it is operating, leaving that for higher level applications to configure.
+
+The [Planet SDK for Python](https://developers.planet.com/docs/pythonclient/)
 leverages this library, and is pre-configured for the Planet Cloud Service used
 by customers.
+s
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -36,8 +36,8 @@ plugins:
               - "!^_"  # exclude all members starting with _
               - "^__init__$"  # but always include __init__ modules and methods
 
-repo_name: platform-auth/planet-auth-python
-repo_url: https://hello.planet.com/code/platform-auth/planet-auth-python
+repo_name: planetlabs/planet-auth-python
+repo_url: https://github.com/planetlabs/planet-auth-python
 #edit_uri: ""
 
 nav:
diff --git a/pyproject.toml b/pyproject.toml
@@ -7,7 +7,7 @@ requires-python = ">=3.9"
 dynamic = ["version"]
 # version = "X.X.X"
 description = "Planet Auth Utility Code"
-readme = "docs/README-pkg.md"
+readme = "docs/index.md"
 authors = [{ name = "Carl Adams", email = "carl.adams@planet.com" }]
 license = {file = "LICENSE"}
 classifiers = [
@@ -66,6 +66,8 @@ dev = [
     "planet-auth[test, docs, build]",
 ]
 internal = [
+    # For Planet Engineering internal usage.  These are Planet internal packages,
+    # and will not be generally available.
     "planet-auth-config >= 2.0.0",
 ]
 

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+TODO: document submitting tickets and PRs. We will likely lean on the SDK process.`