Repository navigation
docs(reference): render cached_embed_fn and gate every name in __all__ - #587
Conversation
…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.
|
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 The |
|
Thanks @aashish254, merged. The new gate caught |
laya.cached_embed_fnis exported, and the README tells people to wrap their embedder in it, but no page underdocs/named it — so it was the one function in that paragraph with nothing to look up. Its three shortlisting siblings each have a:::directive inreference/helpers.md; this adds the missing one.The gate is the part meant to last:
tests/test_packaging.pynow readslaya.__all__and fails if an exported name appears nowhere indocs/.What prints
A probe over the tree's own source (
4066d5dvs this branch):zensical build --strict --cleanon the branch:No issues found, and the entry really renders —cached_embed_fnshows up insite/reference/helpers/index.htmlas adoc doc-heading, not just an anchor.Six mutation variants, each patched into the worktree, run, and restored (
restored: True):Wis why the sweep is scoped todocs/: the README already mentionscached_embed_fn, so a whole-tree scan would have let this one through.Nuses a made-up export so the check is a real sweep rather than an assertion about one name, andEcovers the vacuous-pass case.Two notes on how it's written
Reading
__all__from the source rather than importinglayakeeps 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.insertthis suite does at the top, soimport layawould return another checkout. Neither half is true — setuptools appends_EditableFinderafterPathFinder, and the suite inserts nothing. Theastread 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.pyis wired atci.yml:111,ci.yml:237andrelease.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.