[PredictiveManish]

Related issue

Closes #838

What does this PR do?

Adds docs/source/cache.md, a page documenting the kernels cache: where it
lives, how it is laid out on disk, how to inspect it, and how to use it offline.

Motivation

#838 asks for the kernels cache to be documented in more depth. @stevhliu
suggested in the issue that this be a new cache.md page rather than an
expansion of env.md, with env.md linking to it, a short inspection example
linking to cli-cache.md, a short paragraph on verification receipts linking to
security.md, and no FAQ entry. This PR follows that outline.

Changes

• Add docs/source/cache.md: cache location and precedence
  (KERNELS_CACHE -> HF_HUB_CACHE -> HUGGINGFACE_HUB_CACHE -> $HF_HOME/hub
  -> $XDG_CACHE_HOME/huggingface/hub -> ~/.cache/huggingface/hub), on-disk
  layout (snapshots/, blobs/, refs/, .verified-kernels/), inspection with
  kernels cache ls, offline use with HF_HUB_OFFLINE=1, and cleanup notes.
• Add cache to the "Use kernels" section of docs/source/_toctree.yml.
• docs/source/env.md: link the KERNELS_CACHE entry to the new page, and add
  an HF_HUB_OFFLINE entry. Happy to drop the latter if you'd rather keep this
  file untouched.
• docs/source/cli-cache.md and docs/source/security.md: link back to the new
  page.

Testing

Docs-only change, no code paths touched. I verified that every relative link and
anchor in docs/source resolves, and checked the page's claims against
kernels/hf_hub.py, kernels/_versions.py, kernels/cli/cache.py,
kernels/digest.py, kernels-common/src/hf.rs and
kernels-common/src/signing/receipt.rs. I did not run doc-builder locally; the
build_pr_documentation CI job will render it.

Checklist

• This PR is linked to an issue that was discussed and approved
• I have tested these changes locally
• New/changed functionality has test coverage (not applicable, docs only)
• LLM disclosure:
  • I did not use an LLM to create this PR.
  • I used an LLM for assistance while creating this PR.
  • This PR was mostly or completely generated by an LLM.

[github-actions]

Hi @PredictiveManish, thanks for your interest in contributing!

This project requires that pull request authors are vouched, and you are not in the list of vouched users.

This PR will be closed automatically. See https://github.com/huggingface/kernels/blob/main/CONTRIBUTING.md for more details.

[sayakpaul]

Cc: @stevhliu

[HuggingFaceDocBuilderDev]

The docs for this PR live here. All of your documentation changes will be reflected on that endpoint. The docs are available until 30 days after the last update.