docs: publish the documentation with Zensical on Read the Docs

.github/workflows/docs.yml

@@ -0,0 +1,48 @@
+name: Docs
+
+on:
+  push:
+    branches: [ "master" ]
+    paths:
+      - 'docs/**'
+      - 'fastapi_cachex/**'
+      - 'README.md'
+      - 'CHANGELOG.md'
+      - 'zensical.toml'
+      - 'pyproject.toml'
+      - 'uv.lock'
+      - '.github/workflows/docs.yml'
+  pull_request:
+    branches: [ "master" ]
+    paths:
+      - 'docs/**'
+      - 'fastapi_cachex/**'
+      - 'README.md'
+      - 'CHANGELOG.md'
+      - 'zensical.toml'
+      - 'pyproject.toml'
+      - 'uv.lock'
+      - '.github/workflows/docs.yml'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v7
+
+    - name: Set up Python
+      uses: actions/setup-python@v7
+      with:
+        python-version: "3.14"
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v10.1.0
+
+    # Same command Read the Docs runs; a broken link or docstring reference
+    # fails the PR here instead of the published site.
+    - name: Sync dependencies
+      run: uv sync --frozen --only-group docs --no-install-project
+
+    - name: Build (strict)
+      run: uv run --no-sync zensical build --strict

.readthedocs.yaml

@@ -0,0 +1,19 @@
+# Read the Docs build: https://fastapi-cachex.readthedocs.io/
+# Mirrors the docs workflow in CI, so a PR that passes there builds here.
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.14"
+  jobs:
+    install:
+      - pip install uv
+      # mkdocstrings reads the package statically, so it need not be installed.
+      - UV_PROJECT_ENVIRONMENT=$READTHEDOCS_VIRTUALENV_PATH uv sync --frozen --only-group docs --no-install-project
+    build:
+      html:
+        - UV_PROJECT_ENVIRONMENT=$READTHEDOCS_VIRTUALENV_PATH uv run --no-sync zensical build --strict
+    post_build:
+      - mkdir -p $READTHEDOCS_OUTPUT/html/
+      - cp -r site/* $READTHEDOCS_OUTPUT/html/

README.md

@@ -12,7 +12,7 @@
 [![PyPI version](https://img.shields.io/pypi/v/fastapi-cachex.svg?logo=pypi&logoColor=gold&label=PyPI)](https://pypi.org/project/fastapi-cachex)
 [![Python Versions](https://img.shields.io/pypi/pyversions/fastapi-cachex.svg?logo=python&label=Python&logoColor=gold)](https://pypi.org/project/fastapi-cachex/)
 
-[English](README.md) | [繁體中文](docs/README.zh-TW.md)
+[English](https://github.com/allen0099/FastAPI-CacheX/blob/master/README.md) | [繁體中文](https://github.com/allen0099/FastAPI-CacheX/blob/master/docs/README.zh-TW.md)
 
 A high-performance caching extension for FastAPI, providing comprehensive HTTP caching support and optional session management.
 
@@ -36,7 +36,7 @@ A high-performance caching extension for FastAPI, providing comprehensive HTTP c
 - IP address and User-Agent binding (optional security features)
 - Header, bearer token and cookie transports (cookies via
   `FastAPICacheXSessionMiddleware`; the older `SessionMiddleware` is deprecated
-  and removed in 0.4.0 — see [Session Management Guide](docs/SESSION.md))
+  and removed in 0.4.0 — see [Session Management Guide](https://github.com/allen0099/FastAPI-CacheX/blob/master/docs/SESSION.md))
 - Automatic session renewal (sliding expiration)
 - Flash messages for cross-request communication
 - Multiple backend support (Redis, Memcached, In-Memory)
@@ -522,15 +522,15 @@ async def expensive_operation():
 
 ## Documentation
 
-- [Cache Flow Explanation](docs/CACHE_FLOW.md)
-- [Development Guide](docs/DEVELOPMENT.md)
+- [Cache Flow Explanation](https://github.com/allen0099/FastAPI-CacheX/blob/master/docs/CACHE_FLOW.md)
+- [Development Guide](https://github.com/allen0099/FastAPI-CacheX/blob/master/docs/DEVELOPMENT.md)
 - [Known Limitations and Planned Work](https://github.com/allen0099/FastAPI-CacheX/issues)
-- [Changelog](CHANGELOG.md)
-- [Contributing Guidelines](docs/CONTRIBUTING.md)
-- [Session Management Guide](docs/SESSION.md) - Complete guide for session features
-- [State Management Guide](docs/STATE.md) - One-shot OAuth/CSRF state tokens
-- [JWT Claims Guide](docs/JWT_CLAIMS.md) - Claim design and extension points for JWT session tokens
+- [Changelog](https://github.com/allen0099/FastAPI-CacheX/blob/master/CHANGELOG.md)
+- [Contributing Guidelines](https://github.com/allen0099/FastAPI-CacheX/blob/master/docs/CONTRIBUTING.md)
+- [Session Management Guide](https://github.com/allen0099/FastAPI-CacheX/blob/master/docs/SESSION.md) - Complete guide for session features
+- [State Management Guide](https://github.com/allen0099/FastAPI-CacheX/blob/master/docs/STATE.md) - One-shot OAuth/CSRF state tokens
+- [JWT Claims Guide](https://github.com/allen0099/FastAPI-CacheX/blob/master/docs/JWT_CLAIMS.md) - Claim design and extension points for JWT session tokens
 
 ## License
 
-This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.
+This project is licensed under the Apache License 2.0 - see the [LICENSE](https://github.com/allen0099/FastAPI-CacheX/blob/master/LICENSE) file for details.

docs/CONTRIBUTING.md

@@ -31,7 +31,7 @@ Please refer to our [Development Guide](DEVELOPMENT.md) for detailed instruction
 
 1. Update the README.md with details of changes to the interface, if applicable
 2. Add an entry to the `## [Unreleased]` section of
-   [CHANGELOG.md](../CHANGELOG.md) if your change alters behaviour, adds public
+   [CHANGELOG.md](https://github.com/allen0099/FastAPI-CacheX/blob/master/CHANGELOG.md) if your change alters behaviour, adds public
    API, or fixes something a user could have hit. That section is what the
    release notes are built from, and a release refuses to run on an empty one,
    so an omission surfaces — but only at release time, and only as "somebody

docs/README.zh-TW.md

@@ -12,7 +12,7 @@
 [![PyPI version](https://img.shields.io/pypi/v/fastapi-cachex.svg?logo=pypi&logoColor=gold&label=PyPI)](https://pypi.org/project/fastapi-cachex)
 [![Python Versions](https://img.shields.io/pypi/pyversions/fastapi-cachex.svg?logo=python&label=Python&logoColor=gold)](https://pypi.org/project/fastapi-cachex/)
 
-[English](../README.md) | [繁體中文](README.zh-TW.md)
+[English](https://github.com/allen0099/FastAPI-CacheX/blob/master/README.md) | [繁體中文](README.zh-TW.md)
 
 FastAPI-CacheX 是一個為 FastAPI 框架設計的高效能快取擴充套件，提供完整的 HTTP 快取功能支援和可選的 Session 管理。
 
@@ -264,12 +264,12 @@ async def expensive_operation():
 - [快取流程說明](CACHE_FLOW.md)
 - [開發指南](DEVELOPMENT.md)
 - [已知限制與待辦](https://github.com/allen0099/FastAPI-CacheX/issues)
-- [變更紀錄](../CHANGELOG.md)
+- [變更紀錄](https://github.com/allen0099/FastAPI-CacheX/blob/master/CHANGELOG.md)
 - [貢獻指南](CONTRIBUTING.md)
 - [Session 管理指南](SESSION.md) - 完整的 Session 功能使用指南
 - [State 管理指南](STATE.md) - OAuth／CSRF 一次性 state token
 - [JWT Claims 說明](JWT_CLAIMS.md) - JWT session token 的 claim 設計與擴展方式
 
 ## 授權條款
 
-本專案採用 Apache License 2.0 授權條款 - 查看 [LICENSE](../LICENSE) 檔案了解更多細節。
+本專案採用 Apache License 2.0 授權條款 - 查看 [LICENSE](https://github.com/allen0099/FastAPI-CacheX/blob/master/LICENSE) 檔案了解更多細節。

docs/api/backends.md

@@ -0,0 +1,13 @@
+# Backends
+
+Every backend implements [`BaseCacheBackend`][fastapi_cachex.backends.base.BaseCacheBackend].
+
+::: fastapi_cachex.backends.base.BaseCacheBackend
+
+::: fastapi_cachex.backends.memory.MemoryBackend
+
+::: fastapi_cachex.backends.redis.AsyncRedisCacheBackend
+
+::: fastapi_cachex.backends.config.RedisConfig
+
+::: fastapi_cachex.backends.memcached.MemcachedBackend

docs/api/cache-manager.md

@@ -0,0 +1,13 @@
+# CacheManager
+
+Application-level caching of arbitrary JSON-serializable values.
+
+::: fastapi_cachex.manager.CacheManager
+
+::: fastapi_cachex.manager_proxy.CacheManagerProxy
+    options:
+      inherited_members: true
+
+::: fastapi_cachex.dependencies.get_app_cache
+
+::: fastapi_cachex.dependencies.AppCache

docs/api/http-caching.md

@@ -0,0 +1,20 @@
+# HTTP caching
+
+The `@cache` decorator, cache invalidation, and the dependency that exposes the
+configured backend.
+
+::: fastapi_cachex.cache.cache
+
+::: fastapi_cachex.cache.invalidate
+
+::: fastapi_cachex.cache.default_key_builder
+
+::: fastapi_cachex.proxy.BackendProxy
+    options:
+      inherited_members: true
+
+::: fastapi_cachex.dependencies.get_cache_backend
+
+::: fastapi_cachex.dependencies.CacheBackend
+
+::: fastapi_cachex.routes.add_routes

docs/api/session.md

@@ -0,0 +1,23 @@
+# Session
+
+See the [session management guide](../SESSION.md) for how the pieces fit together.
+
+::: fastapi_cachex.session.middleware.FastAPICacheXSessionMiddleware
+
+::: fastapi_cachex.session.config.SessionConfig
+
+::: fastapi_cachex.session.manager.SessionManager
+
+::: fastapi_cachex.session.proxy.SessionManagerProxy
+    options:
+      inherited_members: true
+
+::: fastapi_cachex.session.models.Session
+
+::: fastapi_cachex.session.models.SessionUser
+
+::: fastapi_cachex.session.dependencies
+
+::: fastapi_cachex.session.exceptions
+
+::: fastapi_cachex.session.middleware.SessionMiddleware

docs/api/state.md

@@ -0,0 +1,15 @@
+# State
+
+See the [state management guide](../STATE.md) for the OAuth flow these support.
+
+::: fastapi_cachex.state.manager.StateManager
+
+::: fastapi_cachex.state.models.StateData
+
+::: fastapi_cachex.state.proxy.StateManagerProxy
+    options:
+      inherited_members: true
+
+::: fastapi_cachex.state.dependencies
+
+::: fastapi_cachex.state.exceptions

docs/api/types.md

@@ -0,0 +1,5 @@
+# Types and exceptions
+
+::: fastapi_cachex.types
+
+::: fastapi_cachex.exceptions

docs/changelog.md

@@ -0,0 +1 @@
+--8<-- "CHANGELOG.md"

docs/index.md

@@ -0,0 +1 @@
+--8<-- "README.md"

pyproject.toml

@@ -34,6 +34,7 @@ dependencies = [
 Homepage = "https://github.com/allen0099/FastAPI-CacheX"
 Repository = "https://github.com/allen0099/FastAPI-CacheX.git"
 Issues = "https://github.com/allen0099/FastAPI-CacheX/issues"
+Documentation = "https://fastapi-cachex.readthedocs.io/"
 
 [dependency-groups]
 dev = [
@@ -55,6 +56,11 @@ dev = [
     "types-orjson>=3.6.2",
     "types-redis>=4.6.0.20241004",
 ]
+docs = [
+    # Pre-1.0: upgrades are deliberate, not automatic.
+    "zensical>=0.0.65,<0.1",
+    "mkdocstrings-python>=2.0",
+]
 
 [project.optional-dependencies]
 memcache = ["pymemcache"]