From 79eb12aa529b09765ddaac46c031b0b23d39e316 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 7 Oct 2026 11:10:15 +0000 Subject: [PATCH] docs: name and link the example file before every snippet include (#394) GitHub renders a page under docs/ without expanding `--8<--`, so a reader there saw only the include line where the code should be. The sentence before each include now links the example file on GitHub, in both languages, the README says so once for the whole docs/ tree, and the development guide records the convention. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01UTXhK1BtwXTBDaouEcKtpW --- README.md | 5 +++++ docs/APP_CACHE.md | 2 +- docs/BACKENDS.md | 2 +- docs/DEVELOPMENT.md | 5 +++++ docs/HTTP_CACHING.md | 6 ++++-- docs/JWT_CLAIMS.md | 6 +++++- docs/STATE.md | 2 ++ i18n/zh-TW/docs/APP_CACHE.md | 2 +- i18n/zh-TW/docs/BACKENDS.md | 2 +- i18n/zh-TW/docs/HTTP_CACHING.md | 4 +++- i18n/zh-TW/docs/JWT_CLAIMS.md | 6 +++++- i18n/zh-TW/docs/STATE.md | 2 ++ 12 files changed, 35 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index a530880..e170bed 100644 --- a/README.md +++ b/README.md @@ -101,6 +101,11 @@ async def report(cache: AppCache): ## Documentation +The guides are built from `docs/` into the site linked below. Read them there: +a code block that includes one of the runnable examples renders on the site, +while GitHub shows only its `--8<--` include line (the sentence before each +block links the example file). + - [Migrating to 0.4.0](https://fastapi-cachex.readthedocs.io/en/latest/MIGRATING_0_4/) — what 0.4.0 changes and how to upgrade from 0.3.x - [HTTP caching](https://fastapi-cachex.readthedocs.io/en/latest/HTTP_CACHING/) — the `@cache` decorator, Cache-Control directives, cache keys, invalidation and monitoring routes - [Application cache](https://fastapi-cachex.readthedocs.io/en/latest/APP_CACHE/) — `CacheManager` diff --git a/docs/APP_CACHE.md b/docs/APP_CACHE.md index 003aa30..861473f 100644 --- a/docs/APP_CACHE.md +++ b/docs/APP_CACHE.md @@ -48,7 +48,7 @@ Complete runnable example: [`examples/app_cache.py`](https://github.com/allen009 `@cached` does what `get_or_set()` does for a plain function, keyed on its arguments, so a loader or a call to another service is written once and -cached wherever it is called: +cached wherever it is called. From [`examples/app_cache.py`](https://github.com/allen0099/FastAPI-CacheX/blob/master/examples/app_cache.py): ```python diff --git a/docs/BACKENDS.md b/docs/BACKENDS.md index 12bfbc8..bc14090 100644 --- a/docs/BACKENDS.md +++ b/docs/BACKENDS.md @@ -242,7 +242,7 @@ answers again. ## Closing a backend Every backend has `aclose()`, which releases what it holds open. Call it on -shutdown, at the end of the FastAPI lifespan: +shutdown, at the end of the FastAPI lifespan, as [`examples/redis_backend.py`](https://github.com/allen0099/FastAPI-CacheX/blob/master/examples/redis_backend.py) does: ```python diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index 5df9262..4ec463e 100644 --- a/docs/DEVELOPMENT.md +++ b/docs/DEVELOPMENT.md @@ -268,6 +268,11 @@ its English comments on the Traditional Chinese site too; explain it in the text around the fence. `README.md` keeps its quick start inline, since PyPI and GitHub render it without snippets. +GitHub renders a page under `docs/` without expanding the include: the reader +sees the bare `--8<--` line. So the sentence before every fence names the +example file and links to it on GitHub, in both languages (#394); the +`README.md` says the same once for the whole `docs/` tree. + ### Traditional Chinese translation A Traditional Chinese (`zh-TW`) translation is published at diff --git a/docs/HTTP_CACHING.md b/docs/HTTP_CACHING.md index 789355a..c11c923 100644 --- a/docs/HTTP_CACHING.md +++ b/docs/HTTP_CACHING.md @@ -9,6 +9,8 @@ Complete runnable example: [`examples/http_cache.py`](https://github.com/allen00 ## The `@cache` decorator +The routes of [`examples/http_cache.py`](https://github.com/allen0099/FastAPI-CacheX/blob/master/examples/http_cache.py): + ```python --8<-- "examples/http_cache.py:routes" @@ -910,8 +912,8 @@ keys from a `key_builder` that does not use `build_cache_key()`. > the routes on an internal-only app. For a local or test app that should stay > open, pass `dependencies=[]` to opt out deliberately. -The runnable example guards them with a token from an environment variable, and -keeps them closed while the variable is unset: +[`examples/http_cache.py`](https://github.com/allen0099/FastAPI-CacheX/blob/master/examples/http_cache.py) guards them with a token from an environment variable, +and keeps them closed while the variable is unset: ```python diff --git a/docs/JWT_CLAIMS.md b/docs/JWT_CLAIMS.md index b6cdef1..6b4cfc0 100644 --- a/docs/JWT_CLAIMS.md +++ b/docs/JWT_CLAIMS.md @@ -178,7 +178,7 @@ await session_manager.delete_session("session-abc123") If your application needs additional JWT claims, write your own serializer and pass an instance to `SessionManager` through its `token_serializer` argument. Any object with `to_string(token) -> str` and `from_string(token_str) -> SessionToken` methods (the `TokenSerializer` protocol) will do; `from_string()` should raise `ValueError` for invalid tokens, which `SessionManager` converts into `SessionTokenError`. -The base class below does what the built-in `JWTTokenSerializer` does and leaves two hooks for the extra claims. It keeps its own copy of the settings, read from the public `SessionConfig` fields, instead of reaching into `JWTTokenSerializer`'s private attributes, which may change in any release. Like the built-in serializer, it follows `token.expires_at` in `to_string()`, so `exp` keeps up with sliding expiration. +The base class below does what the built-in `JWTTokenSerializer` does and leaves two hooks for the extra claims. It keeps its own copy of the settings, read from the public `SessionConfig` fields, instead of reaching into `JWTTokenSerializer`'s private attributes, which may change in any release. Like the built-in serializer, it follows `token.expires_at` in `to_string()`, so `exp` keeps up with sliding expiration. It is the `serializer` part of [`examples/session_jwt_claims.py`](https://github.com/allen0099/FastAPI-CacheX/blob/master/examples/session_jwt_claims.py). ```python @@ -211,6 +211,8 @@ class ExtendedJWTSerializer(CustomClaimsJWTSerializer): ### Example 2: Adding Multi-Tenant Custom Claims +From [`examples/session_jwt_claims.py`](https://github.com/allen0099/FastAPI-CacheX/blob/master/examples/session_jwt_claims.py): + ```python --8<-- "examples/session_jwt_claims.py:multi-tenant" @@ -221,6 +223,8 @@ class ExtendedJWTSerializer(CustomClaimsJWTSerializer): #### Option 1: Pass it to `SessionManager` (recommended) +From [`examples/session_jwt_claims.py`](https://github.com/allen0099/FastAPI-CacheX/blob/master/examples/session_jwt_claims.py): + ```python --8<-- "examples/session_jwt_claims.py:setup" diff --git a/docs/STATE.md b/docs/STATE.md index f1f3fe5..2612f6c 100644 --- a/docs/STATE.md +++ b/docs/STATE.md @@ -26,6 +26,8 @@ The quick start below is the complete, runnable [`examples/oauth_state.py`](http ## Quick start +This is [`examples/oauth_state.py`](https://github.com/allen0099/FastAPI-CacheX/blob/master/examples/oauth_state.py): + ```python --8<-- "examples/oauth_state.py" diff --git a/i18n/zh-TW/docs/APP_CACHE.md b/i18n/zh-TW/docs/APP_CACHE.md index 391173c..fd55396 100644 --- a/i18n/zh-TW/docs/APP_CACHE.md +++ b/i18n/zh-TW/docs/APP_CACHE.md @@ -44,7 +44,7 @@ await manager.clear_pattern("user:*") # 比對 "myapp:user:*" ## 快取一個函式 {#caching-a-function} -`@cached` 對一般函式做的事與 `get_or_set()` 相同，以函式的引數作為鍵，因此載入資料或呼叫其他服務的函式只要寫一次，在任何地方呼叫都會被快取： +`@cached` 對一般函式做的事與 `get_or_set()` 相同，以函式的引數作為鍵，因此載入資料或呼叫其他服務的函式只要寫一次，在任何地方呼叫都會被快取。以下取自 [`examples/app_cache.py`](https://github.com/allen0099/FastAPI-CacheX/blob/master/examples/app_cache.py)（程式碼註解為英文）： ```python diff --git a/i18n/zh-TW/docs/BACKENDS.md b/i18n/zh-TW/docs/BACKENDS.md index b5acffe..9dddd85 100644 --- a/i18n/zh-TW/docs/BACKENDS.md +++ b/i18n/zh-TW/docs/BACKENDS.md @@ -146,7 +146,7 @@ BackendProxy.set(backend) ## 關閉後端 {#closing-a-backend} -每個後端都有 `aclose()`，用來釋放它持有的連線與背景工作。請在關閉應用程式時，於 FastAPI lifespan 的結尾呼叫它： +每個後端都有 `aclose()`，用來釋放它持有的連線與背景工作。請在關閉應用程式時，於 FastAPI lifespan 的結尾呼叫它，如 [`examples/redis_backend.py`](https://github.com/allen0099/FastAPI-CacheX/blob/master/examples/redis_backend.py) 所示（程式碼註解為英文）： ```python diff --git a/i18n/zh-TW/docs/HTTP_CACHING.md b/i18n/zh-TW/docs/HTTP_CACHING.md index e7c67fa..6e84339 100644 --- a/i18n/zh-TW/docs/HTTP_CACHING.md +++ b/i18n/zh-TW/docs/HTTP_CACHING.md @@ -6,6 +6,8 @@ ## `@cache` 裝飾器 {#the-cache-decorator} +以下是 [`examples/http_cache.py`](https://github.com/allen0099/FastAPI-CacheX/blob/master/examples/http_cache.py) 的路由（程式碼註解為英文）： + ```python --8<-- "examples/http_cache.py:routes" @@ -521,7 +523,7 @@ add_routes( > [!WARNING] > **這些路由本身沒有任何身分驗證。** `include_in_schema=False` 只是讓它們不出現在 OpenAPI 文件中；任何猜到路徑的人都能讀取。它們會暴露整個路由結構（包含查詢字串），設定 `include_content_preview=True` 時還會暴露每個快取回應的開頭。因此 `dependencies` 為必填：請傳入 `dependencies=[Depends(your_auth)]`，或將路由掛載在僅供內部使用的應用程式上。若本機或測試用的應用程式確實要保持開放，請傳入 `dependencies=[]` 明確選擇不設防護。 -可執行範例以環境變數中的權杖保護它們，未設定該變數時路由一律拒絕存取： +[`examples/http_cache.py`](https://github.com/allen0099/FastAPI-CacheX/blob/master/examples/http_cache.py) 以環境變數中的權杖保護它們，未設定該變數時路由一律拒絕存取（程式碼註解為英文）： ```python diff --git a/i18n/zh-TW/docs/JWT_CLAIMS.md b/i18n/zh-TW/docs/JWT_CLAIMS.md index 0eedc1e..39e6f77 100644 --- a/i18n/zh-TW/docs/JWT_CLAIMS.md +++ b/i18n/zh-TW/docs/JWT_CLAIMS.md @@ -178,7 +178,7 @@ await session_manager.delete_session("session-abc123") 如果你的應用程式需要額外的 JWT claim，請撰寫自己的序列化器，並透過 `SessionManager` 的 `token_serializer` 參數傳入實例。任何具有 `to_string(token) -> str` 與 `from_string(token_str) -> SessionToken` 方法的物件（即 `TokenSerializer` 協定）都可以；`from_string()` 遇到無效權杖時應拋出 `ValueError`，`SessionManager` 會將它轉換為 `SessionTokenError`。 -下面的基底類別做的事與內建的 `JWTTokenSerializer` 相同，並為額外的 claim 留下兩個掛鉤。它從 `SessionConfig` 的公開欄位讀取設定並自行保存，而不是存取 `JWTTokenSerializer` 的私有屬性，因為那些屬性在任何版本都可能改變。它與內建序列化器一樣，在 `to_string()` 中採用 `token.expires_at`，讓 `exp` 持續跟著滑動過期。 +下面的基底類別做的事與內建的 `JWTTokenSerializer` 相同，並為額外的 claim 留下兩個掛鉤。它從 `SessionConfig` 的公開欄位讀取設定並自行保存，而不是存取 `JWTTokenSerializer` 的私有屬性，因為那些屬性在任何版本都可能改變。它與內建序列化器一樣，在 `to_string()` 中採用 `token.expires_at`，讓 `exp` 持續跟著滑動過期。它是 [`examples/session_jwt_claims.py`](https://github.com/allen0099/FastAPI-CacheX/blob/master/examples/session_jwt_claims.py) 的 `serializer` 部分（程式碼註解為英文）。 ```python @@ -211,6 +211,8 @@ class ExtendedJWTSerializer(CustomClaimsJWTSerializer): ### 範例 2：加入多租戶的自訂 claim {#example-2-adding-multi-tenant-custom-claims} +以下取自 [`examples/session_jwt_claims.py`](https://github.com/allen0099/FastAPI-CacheX/blob/master/examples/session_jwt_claims.py)（程式碼註解為英文）： + ```python --8<-- "examples/session_jwt_claims.py:multi-tenant" @@ -221,6 +223,8 @@ class ExtendedJWTSerializer(CustomClaimsJWTSerializer): #### 做法 1：傳給 `SessionManager`（建議） {#option-1-pass-it-to-sessionmanager-recommended} +以下取自 [`examples/session_jwt_claims.py`](https://github.com/allen0099/FastAPI-CacheX/blob/master/examples/session_jwt_claims.py)（程式碼註解為英文）： + ```python --8<-- "examples/session_jwt_claims.py:setup" diff --git a/i18n/zh-TW/docs/STATE.md b/i18n/zh-TW/docs/STATE.md index ba0b750..60a43cf 100644 --- a/i18n/zh-TW/docs/STATE.md +++ b/i18n/zh-TW/docs/STATE.md @@ -15,6 +15,8 @@ State 與 HTTP 快取存放在同一個後端，但使用自己的鍵前綴（ ## 快速開始 {#quick-start} +以下是 [`examples/oauth_state.py`](https://github.com/allen0099/FastAPI-CacheX/blob/master/examples/oauth_state.py)（程式碼註解為英文）： + ```python --8<-- "examples/oauth_state.py"