[lpm0073]

The Release workflow tags a version and publishes smarter-api to PyPI by itself, but docs.smarter-python.smarter.sh was published only when a maintainer ran make sphinx-publish with AWS credentials, so after a release the site could describe an older version than PyPI serves. cache-results already publishes its site from its Release workflow; this brings smarter-python in line with it. Written against the Smarter platform at release v0.36.20.

Release workflow (.github/workflows/release.yml):

• A new publish-docs job, copied from cache-results' job of the same name, runs after verify-pypi has installed the release back from PyPI, so the site documents exactly what pip install smarter-api installs. Prereleases from alpha and beta never reach PyPI, and so never reach the site.
• It checks out the release tag, builds the site with sphinx-build -W, signs in to AWS with aws-actions/configure-aws-credentials, runs the same s3 sync and CloudFront invalidation as make sphinx-publish, then waits until the site's index page shows the new version, which html_title in docs/source/conf.py carries.
• It runs in a new docs environment, to be limited to main in the repository's settings as the pypi environment is, and only when the repository variable PUBLISH_DOCS is true.
• The role, bucket and distribution come from the repository variables DOCS_AWS_ROLE_ARN, DOCS_BUCKET and DOCS_DISTRIBUTION_ID, because this public repository must not contain an account or distribution id. The header comment lists the job and its variables.

AWS access (terraform/docs/github_actions.tf, variables.tf, outputs.tf):

• The role smarter-python-docs-publisher, which the job assumes with its GitHub OIDC token, so no AWS access key is stored in GitHub. Its trust policy accepts only a job in this repository's docs environment (variables github_repository and github_environment), and its policy allows only listing, reading, writing and deleting objects in the docs bucket, and creating and reading invalidations of its distribution.
• GitHub's OIDC provider is one per AWS account and cache-results' terraform/docs creates it, so this stack reads it with a data source instead of creating it; a second aws_iam_openid_connect_provider would fail to apply. Apply cache-results' stack first.
• A new output, publisher_role_arn, is the value of DOCS_AWS_ROLE_ARN; bucket_name and distribution_id are those of DOCS_BUCKET and DOCS_DISTRIBUTION_ID.

Documentation: ADR-027 records the decision and the alternatives, which were an AWS key, publishing on every push to main, publishing prereleases, and creating a second OIDC provider. ADR-023, the README, and the smarter-python-release and smarter-sphinx-docs skills describe the job, its variables and environment, the dependency on cache-results' stack, and make sphinx-publish as the way to publish a docs fix between releases.

Checked with actionlint, terraform fmt and validate, the pre-commit hooks and make sphinx-build. The job first runs on the next release from main. Before then, apply terraform/docs (make terraform-plan, make terraform-apply), create the docs environment limited to main, and set DOCS_AWS_ROLE_ARN, DOCS_BUCKET, DOCS_DISTRIBUTION_ID and PUBLISH_DOCS. Until PUBLISH_DOCS is true, the job is skipped.

Pull Request Template

Type of Change

• New feature
• Bug fix
• Documentation
• Refactor
• Chore

Resolves

• Fixes #[Add issue number here.]

Changes

Describe what this Pull Request does

Testing

Describe the testing that has been done or needs to be done

Screenshots

Add any relevant screenshots

Dependencies

List dependencies

Breaking Changes

Describe any breaking changes

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[lpm0073]

🎉 This PR is included in version 0.6.0-alpha.1 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀

[lpm0073]

🎉 This PR is included in version 0.6.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀

[lpm0073]

🎉 This PR is included in version 1.0.0-alpha.1 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀