[Docs] Complete documentations - #61
Open
haochengxia wants to merge 1 commit into
Open
Conversation
Collaborator
Author
|
@codex review |
Four English pages were `[TBD]` placeholders and `examples/simulation.md` carried 19 more `[TBD]` sections. Fill them in, verified against the wrapper source rather than assumed: - `getting_started/installation.md`: requirements, PyPI install, the three optional ML-backed algorithms and their CMake flags, source builds. - `examples/analysis.md`: all 11 `AnalysisOption` fields and 5 `AnalysisParam` fields with real defaults, output files, and the C-reader-only restriction. - `api.md`: hand-written reference for the full exported surface, including the actual enum members (`ReqOp` is `OP_*`, not `READ`/`WRITE`). - `developer.md`: layout, build system, testing, adding an algorithm, docs workflow, CI, releasing. - `examples/simulation.md`: real parameters and defaults for every algorithm, plus the missing `Size` section, the `cache_size`-as-ratio behaviour, and a `CacheBase` method table. Corrections to existing content: Python floor is 3.10 (not 3.9) per `requires-python`; `int_freq` -> `init_freq`; a quickstart snippet used an undefined `lcs`; the FAQ used an absolute URL that broke under locale fallback. Two lists rendered as literal `*` characters because they lacked a preceding blank line. The Chinese tree was three orphaned files at non-mirroring paths, so they never rendered, and they documented an API that does not exist (`cache.get_hit_ratio()`, `PythonHookCache`, `SyntheticReader(dist=...)`). Delete them and translate all ten pages at paths mirroring `en/`. Link-target headings carry explicit `attr_list` anchor IDs so cross-page anchors resolve identically in both languages. `nav_translations` gains the three labels that were still English, and `Getting Started` becomes "入门指南" so it no longer collides with the Quickstart page's own title. `mkdocs build --strict` passes and all 11 anchors are present in the built HTML. Also ignore `docs/site/`, since the existing rule only covered `/site` at the repo root. [Fix] Correct wrong signatures in the type stubs These are the signatures users see in their IDE, and four were wrong: - `TraceAnalyzer.__init__` declared a leading `analyzer` parameter that does not exist and made `analysis_param`/`analysis_option` required. The real signature is `(reader, output_path, analysis_param=None, analysis_option=None)` per `trace_analyzer.py`. - `TraceReader.__init__` declared `**kwargs`; it actually takes `(trace, trace_type=UNKNOWN_TRACE, reader_init_params=None)`, and exposes `c_reader`, which callers rely on to pick the C fast path. - `Request.op` defaulted to `ReqOp.READ`, which is not a member of the enum. `export_cache.cpp` binds the default as `OP_NOP`. - `CacheBase.set_cache_size` was missing. [Feat] Add MQ, LRU-K and Clock2QPlus bindings Bump the libCacheSim submodule to the latest develop (dbf8423..373aee9), which brings three new eviction algorithms, and expose them in Python. New algorithms: - LRUK: evicts by largest backward K-distance (k) - MQ: multi-queue hierarchy with a Qout ghost queue (n_queue, lifetime, qout_size_ratio) - Clock2QPlus: 2Q variant over a Clock main cache (fifo_size_ratio, ghost_size_ratio, move_to_main_threshold, corr_window_ratio) Each is wired through export_cache.cpp, cache.py, __init__.py and the type stubs, covered by the shared parametrized tests, and documented in both the English and Chinese algorithm reference. Two fixes to existing bindings found while checking the docs against the implementation: - BeladySize was unusable: it emitted the key "n-samples" while the C parser only accepts "n-sample", so every construction hit ERROR() and aborted the interpreter. It was absent from every test parametrize list, which is why this went unnoticed. Added regression tests for BeladySize and Belady. - WTinyLFU's window_size was described as a fraction of the main cache. WTinyLFU.c scales the total cache size by it and gives the main cache the remainder, so the docstring and both translations now say total. Also completed the CacheBase type stub, which was missing its admissioner parameter. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> [Fix] Lower macOS deployment target to 11.0 The pin tracked the GitHub runner OS rather than a real requirement (see 77790b4, "As GitHub upgrades its macOS machine to 15.0"). Those are unrelated: the deployment target sets the minimum macOS a wheel supports, so following the runner silently dropped every macOS below it. scikit-build-core gives cmake.define the highest precedence when deriving the wheel's platform tag, so every build produced a macosx_15_0_arm64 wheel. That is incompatible with the macos-14 matrix leg, and with the python-build-standalone interpreters from `uv python install`, which target macOS 11.0 -- so `uv pip install -e .` rejected the wheel it had just built. libCacheSim itself pins no deployment target anywhere and needs only C++17, so 11.0 (the floor for Apple Silicon) is safe. Wheels are now tagged macosx_11_0_arm64 and install on macOS 11+ instead of 15+ only.
haochengxia
force-pushed
the
docs/complete-and-translate
branch
from
August 24, 2026 05:34
b14964f to
c0522ed
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.
No description provided.