Context & Motivation
In #16535, a minor whitespace discrepancy was introduced in google-cloud-storage/README.rst (.. _Setup Authentication.: vs 4. Set up Authentication._).
Because reST target anchors are whitespace-sensitive, this caused PyPI to reject the release upload for google-cloud-storage v3.14.0 with HTTP 400 (long_description has syntax errors in markup and would not be rendered on PyPI).
Problem
Our current CI presubmits run code linters and unit tests, but do not validate that package descriptions render cleanly against PyPI's validator (readme-renderer). Consequently, documentation markup errors can merge into main and remain unnoticed until release time.
Proposed Solution (Low-Overhead)
To catch these issues early without adding noticeable burden to CI, we can add a lightweight check to the existing lint.yml workflow scoped only to modified packages in the PR (matching how linting currently targets changed packages):
- Option A (Fastest, ~100ms per PR): Run a script using
readme-renderer[md] directly against changed README.rst / README.md files as part of the lint job.
- Option B (Recommended, ~1s per changed package): Run
python -m build --sdist packages/<changed_pkg> followed by twine check --strict dist/* in the existing lint runner to validate both description rendering and packaging metadata without creating heavy per-package virtual environments.
Context & Motivation
In #16535, a minor whitespace discrepancy was introduced in
google-cloud-storage/README.rst(.. _Setup Authentication.:vs4.Set up Authentication._).Because reST target anchors are whitespace-sensitive, this caused PyPI to reject the release upload for
google-cloud-storagev3.14.0 with HTTP 400 (long_description has syntax errors in markup and would not be rendered on PyPI).Problem
Our current CI presubmits run code linters and unit tests, but do not validate that package descriptions render cleanly against PyPI's validator (
readme-renderer). Consequently, documentation markup errors can merge intomainand remain unnoticed until release time.Proposed Solution (Low-Overhead)
To catch these issues early without adding noticeable burden to CI, we can add a lightweight check to the existing
lint.ymlworkflow scoped only to modified packages in the PR (matching how linting currently targets changed packages):readme-renderer[md]directly against changedREADME.rst/README.mdfiles as part of the lint job.python -m build --sdist packages/<changed_pkg>followed bytwine check --strict dist/*in the existing lint runner to validate both description rendering and packaging metadata without creating heavy per-package virtual environments.