Skip to content

docs(reference): render cached_embed_fn and gate every name in __all__ - #587

Merged
NandhaKishorM merged 2 commits into
NandhaKishorM:mainfrom
aashish254:feat-docs-export-coverage
Sep 27, 2026
Merged

NandhaKishorM merged 2 commits into
NandhaKishorM:mainfrom
aashish254:feat-docs-export-coverage

Conversation

@aashish254

@aashish254 aashish254 commented Sep 26, 2026 •

Copy link
Copy Markdown
Contributor

laya.cached_embed_fn is exported, and the README tells people to wrap their embedder in it, but no page under docs/ named it — so it was the one function in that paragraph with nothing to look up. Its three shortlisting siblings each have a ::: directive in reference/helpers.md; this adds the missing one.

The gate is the part meant to last: tests/test_packaging.py now reads laya.__all__ and fails if an exported name appears nowhere in docs/.

What prints

A probe over the tree's own source (4066d5d vs this branch):

before                                             after
  21 pages under docs/, 31 `:::` directives          21 pages under docs/, 32 `:::` directives
  40 of 41 names in ALL are mentioned in docs/       41 of 41 names in ALL are mentioned in docs/
  MISSING cached_embed_fn                            every export is reachable from the docs site

zensical build --strict --clean on the branch: No issues found, and the entry really renders — cached_embed_fn shows up in site/reference/helpers/index.html as a doc doc-heading, not just an anchor.

Six mutation variants, each patched into the worktree, run, and restored (restored: True):

P  parent commit (no gate, no docs entry)  exit=0  43 passed 0 failed
A  gate added, docs entry still missing    exit=1  45 passed 1 failed   names cached_embed_fn
S  shipped: gate + docs entry              exit=0  46 passed 0 failed
W  sweep widened to every repo .md         exit=0  46 passed 0 failed   passes WITHOUT the docs entry
N  a brand-new export no page names        exit=1  45 passed 1 failed   names it
E  __all__ emptied                          exit=1  45 passed 1 failed   hits the population guard

W is why the sweep is scoped to docs/: the README already mentions cached_embed_fn, so a whole-tree scan would have let this one through. N uses a made-up export so the check is a real sweep rather than an assertion about one name, and E covers the vacuous-pass case.

Two notes on how it's written

Reading __all__ from the source rather than importing laya keeps this check on the tree the rest of the suite already walks, and keeps the file import-free: no lazy __getattr__ name resolves, torch never loads, and a computed __all__ becomes a reported guard instead of an import result.

(Correction, and the reason for fba584a: the first version of this paragraph and of the code comment said an editable install's meta-path finder outranks the sys.path.insert this suite does at the top, so import laya would return another checkout. Neither half is true — setuptools appends _EditableFinder after PathFinder, and the suite inserts nothing. The ast read is still the one I want, just for the ordinary reasons.)

The gate checks that a name is mentioned, not that it has a ::: directive. 30 of the 41 exports have a directive today, and the remaining 11 (PredictHook/BaseHook/AsyncHook/Hook, RLAgent, decide, DecisionResult, detect_language, answer_confidence, __version__) are a bigger job — #419 already covers one of them, so I left the stricter check out rather than pre-empting that.

No workflow change: tests/test_packaging.py is wired at ci.yml:111, ci.yml:237 and release.yml:50.

Expected overlap: #500 edits the same test file about 115 lines above this block, and #419 adds a directive to the same region of this page — whichever of ours lands second will need a one-line touch.

…s named

`laya.cached_embed_fn` is in `__all__` and the README shows callers wrapping an
embedder in it, but no page under docs/ named it, so the one function a user is
told to reach for had no reference entry.  Its three shortlisting siblings each
have a `:::` directive in reference/helpers.md; this adds the missing fourth.

The gate is the part meant to last: `tests/test_packaging.py` now reads
`laya.__all__` as a literal from the tree's source and fails if any exported name
appears nowhere in docs/, with two guards so an empty page list or a computed
`__all__` cannot make the sweep pass vacuously.  The list is parsed rather than
imported because an editable install registers a meta-path finder that wins over
the `sys.path.insert` the suite does at the top, so `import laya` there silently
returns another checkout's package.
The first version of this comment claimed an editable install's meta-path finder
outranks the suite's `sys.path.insert`, so `import laya` would return another
checkout.  Neither half is true here: setuptools *appends* `_EditableFinder` after
`PathFinder` (verified from the installed finder, and by importing a worktree with
`sys.path.insert` from an unrelated cwd), and this suite inserts nothing.  What is
true is that the check reads the same tree it walks, imports nothing, and turns a
computed `__all__` into a reported guard rather than an import result.
@aashish254

Copy link
Copy Markdown
Contributor Author

Edited the body and pushed one comment-only commit (fba584a). The code comment and a paragraph here said an editable install's meta-path finder beats sys.path.insert, so import laya in a test silently returns another checkout. I re-checked that and it is wrong: setuptools appends _EditableFinder after PathFinder, and this suite never touches sys.path.

The ast read stays, for the ordinary reasons — no import, no torch, and a computed __all__ hits the guard instead of quietly yielding whatever is installed. Nothing in the check changed, and the six mutation rows still print the same.

@NandhaKishorM
NandhaKishorM merged commit 188aa9f into NandhaKishorM:main Sep 27, 2026
22 checks passed
@NandhaKishorM

Copy link
Copy Markdown
Owner

Thanks @aashish254, merged. The new gate caught check_min_confidence and flag_low_confidence from #489, so they now have an Abstention section in the helpers reference. It ships in 0.3.21.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants