diff --git a/RELEASE.md b/RELEASE.md index be69ca39..b0aedbdb 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -16,18 +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 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 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..5bdba43f --- /dev/null +++ b/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.) + +---- 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 }}

+
{% 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",