Skip to content

docs: build versioned documentation site after PR #52 quickstart #48

Open

Description

@agustin18

2026-11-21 post-merge status: PR #89 MERGED via squash commit b118890c67c10cc6315af21f03e8633b7c3d703c, with CI, docs checker, CodeQL and changelog green. Source and manual-only Pages workflow are now on stable. Not deployed; public URL unverified. Keep #48 OPEN. Required before activation: Settings → Pages → GitHub Actions source; Settings → Environments → github-pages → allow deployment from stable only (plus optional manual approval); manually run docs-pages.yml on reviewed stable; verify actual URL/mobile/search/link resolution; preserve versioned 0.5.0 historical docs when the current site eventually moves to 0.6.0. Merge does not authorize publication. Runbook. Older pre-merge notes below are historical.


2026-11-21 hosting progress: Draft PR #89 prepares a manual-only GitHub Pages workflow, the intended (not verified live) https://agustin18.github.io/fastapi-cache/ URL, 0.5.0 API reference and credible alternatives guide, and published-version documentation strategy. #87 already merged its searchable docs and 464-link build checker. #48 remains open until Pages is configured via GitHub Actions, approved workflow run deployed, exact live URL/mobile/search/links independently checked, and 0.5.0 historical docs preservation strategy confirmed. #89 merge alone must not deploy anything. Hosting plan.


Documentation milestone delivered (2026-11-21): PR #87 MERGED into stable as 8c079c8dbca645f3a2c87cf971c84a6192cbed41 after 32/32 green checks. New Zensical responsive/searchable docs source, verified 0.5.0 quickstart/migration and read-only CI preview now include a fail-closed check over every built HTML page, internal link, target file and fragment, with regression tests. #48 remains OPEN solely for explicit public hosting, versioned historical URL strategy and ongoing published-site maintenance. Do not call the website live until a deployment is enabled and independently verified. Earlier draft notes below are historical.


Target: 0.4.0 documentation track; can deliver independently of code

Work already prepared

PR #52 already adds docs/QUICKSTART.md, corrects stale pre-release text and creates the release-status/provenance page. Do not recreate that work in this issue. Wait for its merge (or coordinate changes against its branch).

Remaining scope

  • Decide on MkDocs Material or a comparable low-maintenance site and publish versioned docs with clear default stable/current vs historical docs.
  • Refactor the long README/MIGRATION/COMPATIBILITY text into navigation: 5-minute quickstart, drop-in migration, Redis vs InMemory, lifecycle, authenticated cache safety, cache key builders, invalidation, TTL/ETag, coders, error semantics, troubleshooting, security/support and API reference.
  • Provide runnable source examples for Redis/InMemory and migration with CI smoke checks; include safe auth/tenant separation tests.
  • CI builds docs, validates internal links and code snippets, keeps release version claims aligned with PyPI metadata.
  • Document unsupported Redis client majors, Redis Cluster namespace clear, experimental Memcached/DynamoDB accurately until support lands.

Done when

Docs are published, navigable, version-aware, and tested; avoid duplicating content already merged by PR #52. The docs site is not a blocker for shipping tested redis-py compatibility in 0.4.0.

Activity

  1. changed the title [-]docs: publish versioned getting-started and migration documentation[/-] [+]docs: build versioned documentation site after PR #52 quickstart[/+] on Nov 19, 2026
  2. 13 remaining items

  3. agustin18 commented on Nov 21, 2026

    @agustin18
    OwnerAuthor

    Hosting handoff / factual status — 2026-11-21

    PR #89 is merged on stable at b118890c; the manual-only .github/workflows/docs-pages.yml is present. There has been no verified deployment and the proposed https://agustin18.github.io/fastapi-cache/ is not accepted as live.

    The currently connected GitHub integration supports reading/modifying repository files/PRs, but does not expose setting Pages build source, editing github-pages environment deployment branch restrictions, or issuing workflow_dispatch. Do not bypass those controls with a branch push or a privileged workflow edit.

    Maintainer-required manual steps (in this order):

    1. Settings → Pages: select GitHub Actions as the Pages build/deployment source.
    2. Settings → Environments → github-pages: restrict deployment branches to stable only; optionally require approval.
    3. Actions → Publish documentation to GitHub Pages (manual): choose stable and manually Run workflow. Record run ID, selected ref, deployment URL and environment approval where relevant.
    4. Independently open the actual deployed URL and /getting-started/, /migration/, /reference/api/, /reference/alternatives/ and privacy guide; test search, mobile layout, internal paths, PyPI 0.5.0 and GitHub release links. Do not assume domain canonicalization.
    5. Mark the live URL and evidence in docs: build versioned documentation site after PR #52 quickstart #48. Only then update the README and publicity tracker to link it. Historical v0.5.0 docs versioning remains a separate open subtask.

    0.5.0 is still the latest published package. No GitHub Pages website, tag or PyPI release was published by these repository changes.

  4. agustin18 commented on Nov 21, 2026

    @agustin18
    OwnerAuthor

    Documentation source review update, 2026-11-21: #93 successfully built the 0.5.0-versioned Zensical site (15 pages, 588 internal links verified) while explaining source-merged, unpublished #85. Docs CI. This is CI preview only: Pages has not been activated/deployed and no public URL verified. Required manual github-pages environment stable restriction, Actions source, manual deployment and live site verification remain open. Do not close #48 or announce a website.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions