Repository navigation
docs: organize the site navigation and check docstrings - #391
Merged
NandhaKishorM merged 3 commits intoSep 24, 2026
Merged
Conversation
The navigation puts ARM64 before the Docker quickstart because pages sort by filename. The root .nav.yml now groups them into Guides, Deployment, Fine-tuning and Reference, and hooks/ and reference/ get a reading order. Zensical supports these awesome-nav files without a new dependency. Unlisted pages and folders appear under Guides. The glob uses ignore_no_matches so the strict build also passes when every page is listed.
The landing page listed guides without explaining where to start. It now explains the three question types and points new readers to the README's installation and quickstart. A table connects common tasks to the guides that cover them.
The strict build passed despite Griffe warnings about three grouped parameter entries. Griffe treated each group as one name, leaving combined entries in the API reference. Split the groups into one entry per parameter, with hook types from laya.hooks, and fail the docs job on log lines starting with griffe:. Use --clean so cached modules can't hide the warnings. AGENTS.md and CONTRIBUTING.md document the check.
Owner
|
Thank you, the site reads much better with a real reading order, and the fallback glob keeps new pages visible without anyone editing the nav. Failing the build on griffe warnings is a smart guard, since the API reference is built from those docstrings. I built it locally with the pinned Zensical and the new navigation renders exactly as described. Merging. |
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
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.
The site navigation sorts pages by filename, which puts ARM64 before the Docker quickstart. This groups the guides by topic and gives them a reading order, while keeping new pages visible without a nav edit. It also adds a task-based landing page and makes Griffe warnings from the API reference fail the docs build. Part of #390.
Navigation.
docs/.nav.ymlsets four sections: Guides, Deployment, Fine-tuning and Reference. Zensical reads these awesome-nav files without a new dependency.hooks/follows the order of the table on its index page, andreference/puts Agent and Router first. A page or folder that isn't listed still appears under Guides, preserving the automatic discovery added in #282.Landing page. It explains the three question types, sends new readers to the README's Installation and Quickstart, and maps common tasks to the guide that covers them.
Docstring warnings. The strict build passes despite Griffe warnings about three grouped parameter entries:
hooks, on_predict_start, on_predict_endin two places, andmax_len, head_max_lenin one. The parameters exist, but Griffe reads each group as a single name, so they render as combined entries. They're now split into one entry per parameter, with the hook types fromlaya.hooks. The docs job fails on log lines starting withgriffe:and uses--cleanso cached modules can't hide those warnings.AGENTS.mdandCONTRIBUTING.mddocument the check.Overlap. #277 and #347 touch the
Args:blocks changed here, so whichever lands second will need to resolve those conflicts while keeping one entry per parameter. #382 adds a link to the old landing page list and will need to put it in the new table. Itsevals.mdpage will appear under Guides through automatic discovery.Checked:
zensical build --strict --cleanpasses with nogriffe:lines. On the base revision it prints six lines for the three grouped entries.ruff checkwith the CI selection,compileallandtests/test_packaging.pypass.