Description
Problem / Background
make webpage-build (Makefile:809-817) has the same unmet MkDocs dependency that #1111 documented for the thirteen docs-* targets, but it is not a docs-* target, so #1111's enumerated scope did not cover it and PR #1122 left it unguarded. It was recorded as a follow-up rather than changed silently.
The target's body is:
rm -rf webpage/site/public/en/manual webpage/site/public/ko/manual
uv run zensical build -f mkdocs.yml -d webpage/site/public/en/manual
uv run zensical build -f mkdocs.ko.yml -d webpage/site/public/ko/manual
cd webpage/site && pnpm install && pnpm build
mkdocs.yml sets docs_dir: docs/en and mkdocs.ko.yml sets docs_dir: docs/ko, and neither directory exists in this checkout. docs/shared, docs/requirements.txt and docs/scripts are also absent, and docs/overrides exists but is empty and untracked, so it is absent from a fresh clone. Those manual sources are maintained in a separate documentation tree, exactly as docs-guard already explains.
The consequence today is that make webpage-build fails partway: the rm -rf has already deleted webpage/site/public/en/manual and webpage/site/public/ko/manual, and only then does zensical error out against a nonexistent docs_dir. The failure is opaque in the same way the docs-* targets were before the guard.
Proposed Solution
Add the existing docs-guard prerequisite to webpage-build so it fails immediately with the same clear message (which already points readers at the published manual at https://mlxcel.lablup.ai/en/manual/) instead of failing partway with a zensical error against a missing docs_dir.
Keep the guard a presence check on docs/en, not an unconditional refusal, so webpage-build still runs exactly as before in a tree that does hold the manual sources. git show 2c6b3465 -- Makefile has the exact shape used for the thirteen guarded targets.
Also update the target's ## help string to carry the same (manual sources not in this checkout) suffix the guarded docs-* targets use, so make help states the dependency rather than making the user discover it by running the target.
Separately, decide whether webpage-deploy (Makefile:819-822, which runs scripts/deploy_webpage.sh) needs the same treatment. The script does not invoke zensical or reference the manual output: it runs pnpm install && pnpm run build in webpage/site and publishes out/. So it does not fail on the missing sources, but it will publish a site whose /en/manual and /ko/manual paths are missing or stale unless webpage-build ran successfully first. Confirm that reading of the script and choose deliberately between guarding it, warning inside it, or leaving it alone with a comment explaining why.
Acceptance Criteria
-
webpage-builddeclaresdocs-guardas a prerequisite. - On a checkout without
docs/en,make webpage-buildfails at the guard before deletingwebpage/site/public/en/manualorwebpage/site/public/ko/manualand before invokinguv. - The guard stays a presence check, so
webpage-buildstill runs end to end in a tree that does hold the manual sources. - The
##help string forwebpage-buildstates that it needs the manual sources, matching the(manual sources not in this checkout)suffix carried by the thirteen guarded targets. -
webpage-deployis evaluated againstscripts/deploy_webpage.sh, and the outcome (guarded, warned, or intentionally left alone) is reflected in the Makefile.
Technical Considerations
docs-guardandDOCS_MANUAL_DIRare defined below the webpage section in the Makefile. Make resolves prerequisites and variables after the whole file is parsed, so no reordering is required, but consider whether moving the guard definition above both sections reads better.webpage-dev(Makefile:805-807) only runspnpm devand does not touch the manual, so it needs no guard.
Activity
chore(build): guard webpage-build against missing MkDocs sources (#1570)