From e0bcaa146dde3ab20a83754b8a8e293240dae3e5 Mon Sep 17 00:00:00 2001 From: "Carl A. Adams" Date: Tue, 8 Apr 2025 23:27:12 -0700 Subject: [PATCH 1/5] 3.0 branch --- RELEASE-PLANNING-3.0.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) create mode 100644 RELEASE-PLANNING-3.0.md diff --git a/RELEASE-PLANNING-3.0.md b/RELEASE-PLANNING-3.0.md new file mode 100644 index 00000000..796a75f1 --- /dev/null +++ b/RELEASE-PLANNING-3.0.md @@ -0,0 +1,13 @@ +# Planet Python Client 3.0 Release Planning + +* Authentication changes: + * Migrate to OAuth2 based authentication mechanisms, leveraging the + [planet-auth-python](https://github.com/planetlabs/planet-auth-python) + library for implementation. + * Deprecate use of the legacy authentication protocol and handling of the + user's password. + * CLI changes to support changes in authentication practices. + * Support for API keys supplied by the user is maintained, but users should + be aware that there are currently no plans for sentinel-hub.com APIs to + support Planet API keys. The longer term roadmap is for all APIs to work + with OAuth service accounts. From 99fc41ca46436e47fd99cd772406dc4649683751 Mon Sep 17 00:00:00 2001 From: "Carl A. Adams" Date: Fri, 11 Apr 2025 17:34:13 -0700 Subject: [PATCH 2/5] remove dead release workflow --- .github/workflows/release.yml | 51 ----------------------------------- 1 file changed, 51 deletions(-) delete mode 100644 .github/workflows/release.yml diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml deleted file mode 100644 index c2ea51ac..00000000 --- a/.github/workflows/release.yml +++ /dev/null @@ -1,51 +0,0 @@ -name: Release to GitHub and PyPI - -on: - workflow_dispatch: - inputs: - prerelease: - description: 'Is this a pre-release?' - required: true - type: boolean - -jobs: - package: - name: Build, verify, & upload package - runs-on: ubuntu-latest - - steps: - - uses: actions/checkout@v3 - - uses: actions/setup-python@v3 - with: - python-version: "3.12" - - - name: Create GitHub Release - uses: actions/create-release@v1 - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # This token is provided by Actions. - with: - tag_name: ${{ github.ref }} - release_name: ${{ github.ref }} - draft: false - prerelease: ${{ inputs.logLevel }} - - - run: python -m pip install build twine check-wheel-contents - - run: python -m build --sdist --wheel . - - run: ls -l dist - - run: check-wheel-contents dist/*.whl - - - name: Check long_description - run: python -m twine check dist/* - - - name: Upload to TestPyPI - uses: pypa/gh-action-pypi-publish@v1.4.2 - with: - repository_url: https://test.pypi.org/legacy/ - user: __token__ - password: ${{ secrets.TEST_PYPI_PASSWORD }} - - - name: Upload to PyPI - uses: pypa/gh-action-pypi-publish@v1.4.2 - with: - user: __token__ - password: ${{ secrets.PYPI_PASSWORD }} \ No newline at end of file From 06fbcd7b58600f6799c1759945307caef0fcde88 Mon Sep 17 00:00:00 2001 From: "Carl A. Adams" Date: Fri, 11 Apr 2025 17:34:38 -0700 Subject: [PATCH 3/5] add step to releas to check doc status. --- RELEASE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/RELEASE.md b/RELEASE.md index be69ca39..455fa12b 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -28,7 +28,7 @@ The SDK follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html) and t 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` 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/) ## Local publishing From db91b0ae21f078cc353ace51462a598fa46b93ea Mon Sep 17 00:00:00 2001 From: "Carl A. Adams" Date: Thu, 24 Apr 2025 20:06:28 -0700 Subject: [PATCH 4/5] Add the version to the docs homepage so a document bundle is self identifying without external framing. --- docs/custom_theme/home.html | 10 +++++++--- docs/hooks/mkdocs_hooks.py | 9 +++++++++ docs/stylesheets/extra.css | 8 ++++++-- mkdocs.yml | 3 +++ pyproject.toml | 2 +- 5 files changed, 26 insertions(+), 6 deletions(-) create mode 100644 docs/hooks/mkdocs_hooks.py diff --git a/docs/custom_theme/home.html b/docs/custom_theme/home.html index 89d6fdcc..dfbc899f 100644 --- a/docs/custom_theme/home.html +++ b/docs/custom_theme/home.html @@ -5,7 +5,11 @@
-

Welcome to the {{ config.site_name }}

+

+ Welcome to the {{ config.site_name }} +
+ Version {{ config.extra.planet_sdk_version }} +

{{ config.site_description }}

Get started @@ -30,11 +34,11 @@

Welcome to the {{ config.site_name }}

powered by MkDocs - and + and Material for MkDocs -
+
{% endblock %} diff --git a/docs/hooks/mkdocs_hooks.py b/docs/hooks/mkdocs_hooks.py new file mode 100644 index 00000000..b12c66a7 --- /dev/null +++ b/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 diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css index 281041a9..d225e081 100644 --- a/docs/stylesheets/extra.css +++ b/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; - } \ No newline at end of file + } diff --git a/mkdocs.yml b/mkdocs.yml index bed60674..7823410b 100644 --- a/mkdocs.yml +++ b/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 diff --git a/pyproject.toml b/pyproject.toml index dd16263c..bf915176 100644 --- a/pyproject.toml +++ b/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", From 7088b470ba9481b477b2c8e937c1a1a42c34d7c7 Mon Sep 17 00:00:00 2001 From: "Carl A. Adams" Date: Thu, 24 Apr 2025 21:43:30 -0700 Subject: [PATCH 5/5] update doc about docs --- RELEASE.md | 37 +++++++++++++++++++++++++----- design-docs/content-plan.md | 4 ++-- design-docs/content-readthedocs.md | 25 ++++++++++++++++++++ 3 files changed, 58 insertions(+), 8 deletions(-) create mode 100644 design-docs/content-readthedocs.md diff --git a/RELEASE.md b/RELEASE.md index 455fa12b..08eda5cb 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -16,19 +16,44 @@ 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`. + * Pre-release versions should _not_ impact the default version of the documentation. Pre-release version may be published as the `latest` version. + * 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`. + ## Local publishing diff --git a/design-docs/content-plan.md b/design-docs/content-plan.md index 5880e64e..abaa284b 100644 --- a/design-docs/content-plan.md +++ b/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: diff --git a/design-docs/content-readthedocs.md b/design-docs/content-readthedocs.md new file mode 100644 index 00000000..9158448b --- /dev/null +++ b/design-docs/content-readthedocs.md @@ -0,0 +1,25 @@ +# _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. +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.) + +----