Fix documentation examples and make the Read the Docs build work

Author: claude

.github/copilot-instructions.md

@@ -17,7 +17,7 @@
 - Use a standard out-of-source CMake build for release-style work: `cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release` then `cmake --build build`.
 - CMake tests are enabled by default. Run `ctest --test-dir _build_dbg --output-on-failure` after the debug build, or the equivalent `build/` test directory if you used a separate build tree.
 - If you change installation, packaging, or the public library surface, also review `test/test_lib.sh`.
-- Use sample traces in `data/` for quick validation unless the task specifically requires the large traces in `2024_google/`.
+- Use sample traces in `data/` for quick validation. They are deliberately tiny, so never use them to compare miss ratios between algorithms; larger traces are listed at https://github.com/cacheMon/cache_dataset.
 
 ## Project-Specific Conventions
 - When adding a new eviction algorithm, reader, or plugin, follow `doc/advanced_lib_extend.md` instead of inventing a new integration path. These changes usually require updates to implementation files, registration headers, CMake lists, CLI/parser wiring, and tests.

.readthedocs.yaml

@@ -11,13 +11,14 @@ build:
   tools:
     python: "3.11"
 
-# Build documentation in the docs/ directory with Sphinx
+# The documentation sources are the Markdown files in doc/, rendered with MyST.
 sphinx:
-  configuration: docs/conf.py
+  configuration: doc/conf.py
+  # The build is warning-free; keep it that way, since a broken cross-reference
+  # is otherwise easy to miss.
+  fail_on_warning: true
 
-# We recommend specifying your dependencies to enable reproducible builds:
-# https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+# Docs-only dependencies; the root requirements.txt is for the analysis scripts.
 python:
   install:
-  - requirements: requirements.txt
-
+    - requirements: doc/requirements.txt

FAQ.md

@@ -1,17 +1,47 @@
-## FAQ
-1. **how to read OracleGeneral trace，how to transform from csv to it? **
-The [oracleGeneral](/libCacheSim/traceReader/customizedReader/oracle/oracleGeneralBin.h) trace is a binary trace, so you cannot direct read as txt file. Each request uses the following data struct 
+# FAQ
+
+### How do I read an oracleGeneral trace, and how do I convert a csv trace into one?
+
+The [oracleGeneral](/libCacheSim/traceReader/customizedReader/oracle/oracleGeneralBin.h) trace is a binary format, so it cannot be read as a text file. Each request is the following struct:
+
 ```c
 struct {
-    uint32_t real_time;
+    uint32_t clock_time;
     uint64_t obj_id;
     uint32_t obj_size;
-    int64_t next_access_vtime;
+    int64_t next_access_vtime;  // -1 if there is no next access
 };
 ```
 
-* Read the trace: we have provided a tool `tracePrint` that you can use to print the trace in plain text, it is compiled and under `bin/`
-* Convert csv to oracleGeneral: we have provided `traceConv` to convert traces. The help menu should be sufficient to get started. 
+* **Read the trace**: use `tracePrint` to print the trace as plain text. It is built into `bin/` alongside `cachesim`.
+  ```bash
+  ./bin/tracePrint ../data/cloudPhysicsIO.oracleGeneral.bin oracleGeneral
+  ```
+* **Convert a csv trace**: use `traceConv`. See [quickstart_traceUtils.md](/doc/quickstart_traceUtils.md), or run `./bin/traceConv --help`.
+  ```bash
+  ./bin/traceConv ../data/cloudPhysicsIO.csv csv \
+      -t "time-col=2,obj-id-col=5,obj-size-col=4,obj-id-is-num=1" \
+      --output-format=oracleGeneral
+  ```
+
+oracleGeneral traces are usually stored zstd-compressed, and libCacheSim reads them without decompressing first.
+
+### What are the units in a trace?
+
+In the sample [cloudPhysicsIO.csv](/data/cloudPhysicsIO.csv), time is in seconds and object size is in bytes.
+
+`next_access_vtime` is a *logical* time: the 1-based request index at which this object is next requested — an absolute position in the trace, not the distance to it — or `-1` when the object is never accessed again. Algorithms subtract the current request count themselves, so encoding a distance here silently changes eviction order. In `cloudPhysicsIO.oracleGeneral.bin`, for instance, request 7 stores `19` and that object is next seen at request 19. Algorithms that need future information, such as [Belady](/libCacheSim/cache/eviction/Belady.c) and BeladySize, rely on it, which is why they only work on oracle traces.
+
+Object ids are hashed unless the reader is told they are already numeric. Pass `obj-id-is-num=true` in `--trace-type-params` when the id column holds numbers — `cachesim` stops with an error if you leave it out on such a trace.
+
+### Why does `cachesim` say "do not support algorithm X"?
+
+Some algorithms are behind an optional build flag because they pull in extra dependencies: GLCache (`-DENABLE_GLCACHE=ON`), LRB (`-DENABLE_LRB=ON`), and 3LCache (`-DENABLE_3L_CACHE=ON`). Rebuild with the relevant flag to enable them. See the [README](/README.md#supported-algorithms) for the full list.
+
+### Where can I get larger traces?
+
+The traces in [data/](/data/) are samples and are **far too small to compare miss ratios between algorithms**. We maintain a list of open-source cache datasets at [cacheMon/cache_dataset](https://github.com/cacheMon/cache_dataset).
+
+---
 
-2. **What are the units in the trace? **
-In the [trace.csv](/data/trace.csv), the time unit is in sec, the next_access_time is the logical time (# requests) between current and the next request (to the same object). The next access time is used by some algorithms that require future information, e.g., Belady. The object id is a hash of raw object id (string or numeric value). 
+More questions? Check the [documentation index](/doc/README.md), search the [issue tracker](https://github.com/1a1a11a/libCacheSim/issues), or ask in [Discussions](https://github.com/1a1a11a/libCacheSim/discussions).