Merge branch 'main' into main-3.0-dev

Author: carl-adams-planet

RELEASE.md

@@ -16,19 +16,43 @@ The SDK follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html) and t
 
 1. Create a new GitHub release:
    * From the GitHub UI:
-     * Navigate to the releases UI
-     * Set tag to release version
-     * Set target to `main`
+     * Navigate to the [releases UI](https://github.com/planetlabs/planet-client-python/releases), and select "Draft a new release".
+     * Choose or create a tag for the release version.  The is expected to simply be the [PEP 440](https://peps.python.org/pep-0440/)
+       compliant semantic version number, without any prefix or other adornments.  Examples, from most to least mature:
+       * Production release: `2.3.4`
+       * Release candidate: `2.3.4rc1`
+       * Beta release: `2.3.4b1`
+       * Alpha release: `2.3.4a1`
+       * Alpha development pre-release build: `2.3.4a1.dev1`
+     * Set target the release branch.  This should normally be `main` for production releases.
      * Set title to tag release version
      * Describe the change(s) that are shipping with this version in the release description
    * Alternatively, create a release from the GitHub CLI:
      * Make sure the pre-requisite [gh](https://cli.github.com/manual/gh) CLI is installed, and optionally review the docs for CLI command [gh release create](https://cli.github.com/manual/gh_release_create)
      * By default, `gh release create` will automatically tag releases from the latest state of the default branch
      * Run CLI command `gh release create {VERSION} --notes "{RELEASE NOTES}"` where `VERSION` is the release version and `RELEASE NOTES` is the description of changes
-2. Verify the successful run of the Github Action `Autopublish to TestPyPI` and validate the test release on [test.pypi.org](https://test.pypi.org/project/planet/)
-3. Run the Github Action `Publish on PyPI`
+2. Verify the successful run of the Github Action [`Autopublish to TestPyPI`](https://github.com/planetlabs/planet-client-python/actions/workflows/autopublish-testpypi.yml) and validate the test release on [test.pypi.org](https://test.pypi.org/project/planet/)
+3. Run the Github Action [`Publish on PyPI`](https://github.com/planetlabs/planet-client-python/actions/workflows/publish-pypi.yml)
 4. Verify the successful run of the Github Action `Publish on PyPI` and validate the release on [pypi.org](https://pypi.org/project/planet/)
-5. Verify the successful publishing of documentation to [Read the Docs](https://planet-sdk-for-python-v2.readthedocs.io/en/latest/)
+5. Verify the successful and correct publishing of documentation to Read the Docs.
+   Read the Docs publishing should be triggered automatically by Github
+   [project webhooks](https://github.com/planetlabs/planet-client-python/settings/hooks).
+   Correct publishing includes verifying that the `default`, `stable`, and `latest`
+   versions of the documentation point to the correct versions, and that the version
+   specific documentation URL also works as expected.  The management of these
+   symbolic documentation versions is handled by Read the Docs
+   [automation rules](https://app.readthedocs.org/dashboard/planet-sdk-for-python/rules/).
+   * Published to [planet-sdk-for-python](https://planet-sdk-for-python.readthedocs.io/en/latest/) (Note the new version-less project slug in DNS name).
+     * _`default`_: [https://planet-sdk-for-python.readthedocs.io/](https://planet-sdk-for-python.readthedocs.io/) - Should point to same version as `stable`.
+     * `stable`: [https://planet-sdk-for-python.readthedocs.io/en/stable/](https://planet-sdk-for-python.readthedocs.io/en/stable/) - Should point to the highest stable release version.
+     * `latest`: [https://planet-sdk-for-python.readthedocs.io/en/latest/](https://planet-sdk-for-python.readthedocs.io/en/latest/) - Should point to the most recent build from `main`.
+     * _`version`_: [https://planet-sdk-for-python.readthedocs.io/en/X.YY.ZZ/](https://planet-sdk-for-python.readthedocs.io/en/X.YY.Z/) - Should point to version `X.YY.ZZ`.
+   * Published to [planet-sdk-for-python-v2](https://planet-sdk-for-python-v2.readthedocs.io/en/latest/) (Note the older "v2" in the project slug in the DNS name).
+     * _`default`_: [https://planet-sdk-for-python-v2.readthedocs.io/](https://planet-sdk-for-python-v2.readthedocs.io/) - Should point to same version as `stable`.
+     * `stable`: [https://planet-sdk-for-python-v2.readthedocs.io/en/stable/](https://planet-sdk-for-python-v2.readthedocs.io/en/stable/) - Should point to the highest stable release version.
+     * `latest`: [https://planet-sdk-for-python-v2.readthedocs.io/en/latest/](https://planet-sdk-for-python-v2.readthedocs.io/en/latest/) - Should point to the most recent build from `main`.
+     * _`version`_: [https://planet-sdk-for-python-v2.readthedocs.io/en/X.YY.ZZ/](https://planet-sdk-for-python-v2.readthedocs.io/en/X.YY.ZZ/) - Should point to version `X.YY.ZZ`.
+   * Pre-release versions should _not_ impact the default version of the documentation. Pre-release version may be published as the `latest` version.
 
 ## Local publishing
 

design-docs/content-plan.md

@@ -1,6 +1,6 @@
 # Content Plan Planet SDK (v2)
 
-This document is a response to the issue #353: Quantify 'accurate and complete documentation' required for initial release. After a review of existing content, the following recommendations have been accepted as part of the V2 release. Documentation tickets will be derived from the recommendations, below.
+This document is a response to the [issue #353](https://github.com/planetlabs/planet-client-python/issues/353): Quantify 'accurate and complete documentation' required for initial release. After a review of existing content, the following  recommendations have been accepted as part of the V2 release. Documentation tickets will be derived from the recommendations, below.
 
 ## Overview
 
@@ -19,7 +19,7 @@ The SDK and CLI are low-level interfaces mirroring much of the API, itself. Whil
 
 We are currently publishing documentation on [planet.com](https://docs.planet.com/develop/sdks/#planet-sdk-for-python-and-cli), [github.com](https://github.com/planetlabs/planet-client-python), and on [readthedocs.com](https://planet-sdk-for-python-v2.readthedocs.io). Providing a single source of truth (SSoT) ensures one definitive source of documentation, reducing the dilution of information, errors, and maintenance efforts.
 
-### Ticket to be filed
+### Tickets to be filed
 
 Implement mkdocs to leverage features of readthedocs.com, but publish only on one platform. This would be planet.com unless we are making a concerted effort to recruit 3rd party contributors to the SDK, in which case, it could stay on readthedocs.com. So the publication landscape would be as follows:
 

design-docs/content-readthedocs.md

@@ -0,0 +1,29 @@
+# _ReadTheDocs.io_ Content Management
+
+## Overview
+Pursuant to the [Content Plan](./content-plan.md) developed as part of the
+v2.0 release of the SDK, [_ReadTheDocs.io_](https://planet-sdk-for-python.readthedocs.io/)
+is used to host the single source of truth for SDK documentation.  SDK documentation
+is largely confined to the specifics of using the SDK.  More general Planet Platform
+narrative and HTTP API documentation should be hosted on the Planet documentation site
+at [docs.planet.com](https://docs.planet.com/).
+
+## Version Management
+_ReadTheDocs.io_ hosts multiple versions of the documentation simultaneously.
+All versions of the documentation will be published under a _ReadTheDocs.io_
+URL that explicitly includes the SDK version so that PyPi published packages
+will always have corresponding _ReadTheDocs.io_ documentation for users.
+
+Additionally, the following symbolic names are maintained:
+* [**default**](https://planet-sdk-for-python.readthedocs.io/) - Should point to same version as `stable`.
+* [**stable**](https://planet-sdk-for-python.readthedocs.io/en/stable/) - Should point to the highest stable release version.
+* [**latest**](https://planet-sdk-for-python.readthedocs.io/en/latest/) - Should point to the most recent build from the current mainline major version branch.
+
+Version management is handled by _ReadTheDocs.io_ [automation rules](https://app.readthedocs.org/dashboard/planet-sdk-for-python/rules/).
+
+## _ReadTheDocs.io_ Planet PBC Account
+Planet currently publishes to _ReadTheDocs.io_ as a [community](https://about.readthedocs.com/pricing/#/community)
+project.  It is understood that this means that ads may be displayed on hosted documentation.  (Ref: cleared
+with Planet Engineering Management in April 2025.)
+
+----

docs/custom_theme/home.html

@@ -5,7 +5,11 @@
     <div class="md-grid md-typeset">
       <div class="mdx-hero">
         <div class="mdx-hero__content">
-          <h1>Welcome to the {{ config.site_name }}</h1>
+          <h1>
+              Welcome to the {{ config.site_name }}
+              <br/>
+              <span class="h1_subtitle">Version {{ config.extra.planet_sdk_version }}</span>
+          </h1>
           <p>{{ config.site_description }}</p>
           <a href="./{{ 'get-started/quick-start-guide' | url }}" title="Get Started" class="md-button md-button--primary md-button--teriary">
             Get started
@@ -30,11 +34,11 @@ <h1>Welcome to the {{ config.site_name }}</h1>
       <div class="md-footer-right">
           powered by
           <a href="https://www.mkdocs.org" title="MkDocs">MkDocs</a>
-          and 
+          and
           <a href="https://squidfunk.github.io/mkdocs-material/"
             title="Material for MkDocs">
               Material for MkDocs</a>
-      </div>    
+      </div>
   </div>
 </footer>
 {% endblock %}

docs/hooks/mkdocs_hooks.py

@@ -0,0 +1,9 @@
+from planet import __version__ as _pl_sdk_version
+
+def on_config(config):
+    """
+    This is for injecting the package version into mkdocs
+    config so it can be used in templates.
+    """
+    config["extra"]["planet_sdk_version"] = _pl_sdk_version
+    return config

docs/stylesheets/extra.css

@@ -47,7 +47,7 @@ section.mdx-container::before{
     background-repeat: no-repeat;
     background-position: right 10% bottom 45%;
     background-size: auto;
-  
+
 }
 
 
@@ -75,6 +75,10 @@ section.mdx-container::before{
     margin-right: 2.5vw;
 }
 
+.h1_subtitle {
+    font-size: smaller;
+}
+
 @media screen and (min-width:76.25em){
     section.md-sidebar--primary{display:none}
 }
@@ -87,4 +91,4 @@ section.mdx-container::before{
 
 .highlight .gp, .highlight .go { /* Generic.Prompt, Generic.Output */
     user-select: none;
-  }
+  }

mkdocs.yml

@@ -64,6 +64,9 @@ plugins:
         - planet
         - docs/custom_theme/
 
+hooks:
+  - docs/hooks/mkdocs_hooks.py
+
 nav:
   - "Get Started":
     - get-started/quick-start-guide.md

pyproject.toml

@@ -36,7 +36,7 @@ dynamic = ["version"]
 test = ["pytest==8.3.3", "anyio", "pytest-cov", "respx>=0.22.0"]
 lint = ["flake8", "mypy", "yapf==0.43.0"]
 docs = [
-  "mkdocs==1.3",
+  "mkdocs==1.4.2",
   "mkdocs-click==0.7.0",
   "mkdocs-material==8.2.11",
   "mkdocstrings==0.18.1",