docs: modular backend and serializer documentation#72
Merged
Conversation
…docs Accuracy (13 critical fixes): - Remove ghost parameters from api-reference.md (pipelined, fast_mode, circuit_breaker as bool, etc.) — replaced with actual DecoratorConfig fields - Rename DefaultSerializer → StandardSerializer everywhere (class name mismatch) - Remove PickleSerializer references (does not exist) from 4 files - Fix type support table conflating StandardSerializer with AutoSerializer - Rewrite adaptive-timeouts.md (documented P99×3x, actual is P95×1.5x) - Rewrite distributed-locking.md (ghost params replaced with LockableBackend protocol) - Fix prometheus-metrics.md ghost params (metrics_enabled etc.) - Fix CachekitConfig fields (remove redis_url, socket_timeout etc.) - Add health_check() to BaseBackend protocol docs (was showing 4/5 methods) - Fix ttl default (3600 → None) - Fix Redis URL default (remove /0 suffix) - Remove get_cache_metrics reference (function doesn't exist) - Fix version annotations (v1.0+ → current version) Style fixes: - Kill corporate language: "enterprise-grade", "Executive Summary", "Why cachekit Wins Everywhere", "Conservative Marketing Claims" - Standardize footers across all 29 doc files (remove stale Last Updated dates) - Add GFM callouts to feature docs - Fix "we" pronoun usage in getting-started.md - Convert rust-serialization.md to redirect stub (was stale) Structural fixes: - Flesh out redis.md (was significantly shorter than other backend docs) - Add footers to all 7 serializer docs (were missing entirely) - Standardize breadcrumbs for ssrf-protection.md and l1-invalidation.md - Normalize cross-reference style (remove ./ prefix) - Fix 3 broken notest markers causing doc test failures - Make configuration.md canonical source for env vars - Consolidate duplicate serializer section in api-reference.md - Standardize Prometheus metric prefix to cachekit_ 124 doc tests pass.
Methodical testing of cachekit vs lru_cache vs cachetools vs aiocache across 10 data type categories and 7 behavioral dimensions. Key findings (engineering, not vibes): - cachekit serializes even in L1-only mode — tuples become lists via MessagePack (consistent behavior regardless of backend) - cachekit handles unhashable args (lists, dicts) via content-based hashing — lru_cache and cachetools raise TypeError - lru_cache on async functions caches the coroutine, not the result (RuntimeError on second call) — cachekit handles async natively - All libraries handle primitives, special floats, bytes, datetime, Decimal, UUID, Enum identically in in-memory mode - cachekit async uses ainvalidate_cache(), not cache_clear()
Fix inaccurate claims based on 50-test head-to-head suite: - Disclose tuple→list serialization in ALL modes (not just Redis) - Add unhashable args and async support to feature matrix - Document lru_cache async footgun (caches coroutine, not result) - Note async cache management uses ainvalidate_cache() - Replace stale "pluggable serializers v1.0+" with honest tradeoff note - Reference test suite and GitHub issues as evidence - Remove "Rust Performance" row (vague, not a user-facing feature) Verified: lru_cache async bug confirmed on Python 3.12, no stdlib fix. References: #73, #74, #75, #76, #77
…o' fix - New docs/serializers/auto.md documenting type preservation capabilities - Update comparison.md: disclose serializer='auto' as the fix for tuple→list, rather than framing it as an unsolvable tradeoff - Add AutoSerializer to serializer index and docs README - Note: tuples not yet preserved by AutoSerializer (tracked in #78)
27Bslash6
force-pushed
the
docs/modular-doc-structure
branch
from
8aab901 to
4fbff7d
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Comprehensive documentation restructure and accuracy audit. Splits monolithic guide files into modular per-topic pages, fixes 54 accuracy findings, adds competitive test suite.
Structure
docs/backends/— 7 pages: README, redis, file, memcached, cachekitio, none (L1-only), customdocs/serializers/— 8 pages: README, default, auto, orjson, arrow, encryption, pydantic, customdocs/guides/files replaced with redirect stubs (backward-compatible)QUICK_START.mdremoved (redundant withgetting-started.md)docs/README.mdslimmed to navigation hubindex.mdrenamed toREADME.mdfor GitHub folder auto-renderingAccuracy (54 findings fixed)
pipelined,fast_mode, etc.)DefaultSerializerrenamed toStandardSerializereverywhere (wrong class name)PickleSerializerreferences removed (doesn't exist)rust-serialization.mdconverted to redirect stub (was stale)health_check()added to BaseBackend protocol docs (was showing 4/5 methods)comparison.mdupdated with honest competitive findings +serializer='auto'fixNew content
docs/backends/none.md— L1-only mode documentationdocs/serializers/auto.md— AutoSerializer type preservation documentationllms.txtcomprehensive rewrite with API examples and full doc maptests/competitive/test_head_to_head.py— 50-test suite vs lru_cache, cachetools, aiocacheDoc contract validation
EncryptionWrapper(master_key=...)needsbytes.fromhex(), not hex stringTest plan
pytest --markdown-docs docs/— 126 passedpytest tests/competitive/test_head_to_head.py— 50 passedRelated issues
#73 #74 #75 #76 #77 #78