Skip to content

docs: organize the site navigation and check docstrings - #391

Merged
NandhaKishorM merged 3 commits into
NandhaKishorM:mainfrom
maxfield-allison:docs-structure
Sep 24, 2026
Merged

NandhaKishorM merged 3 commits into
NandhaKishorM:mainfrom
maxfield-allison:docs-structure

Conversation

@maxfield-allison

Copy link
Copy Markdown
Contributor

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.yml sets 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, and reference/ 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_end in two places, and max_len, head_max_len in 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 from laya.hooks. The docs job fails on log lines starting with griffe: and uses --clean so cached modules can't hide those warnings. AGENTS.md and CONTRIBUTING.md document 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. Its evals.md page will appear under Guides through automatic discovery.

Checked:

  • zensical build --strict --clean passes with no griffe: lines. On the base revision it prints six lines for the three grouped entries.
  • Running the new check against the base revision fails. It passes on this branch and still fails when a broken link is introduced.
  • An unlisted page or folder lands under Guides, and the build passes when every page is listed.
  • ruff check with the CI selection, compileall and tests/test_packaging.py pass.

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.
@NandhaKishorM

Copy link
Copy Markdown
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.

@NandhaKishorM
NandhaKishorM merged commit 771b82c into NandhaKishorM:main Sep 24, 2026
21 checks passed
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