Skip to content

chore(build): guard webpage-build against the missing MkDocs manual sources #1138

Closed

Description

@inureyes

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-build declares docs-guard as a prerequisite.
  • On a checkout without docs/en, make webpage-build fails at the guard before deleting webpage/site/public/en/manual or webpage/site/public/ko/manual and before invoking uv.
  • The guard stays a presence check, so webpage-build still runs end to end in a tree that does hold the manual sources.
  • The ## help string for webpage-build states that it needs the manual sources, matching the (manual sources not in this checkout) suffix carried by the thirteen guarded targets.
  • webpage-deploy is evaluated against scripts/deploy_webpage.sh, and the outcome (guarded, warned, or intentionally left alone) is reflected in the Makefile.

Technical Considerations

  • docs-guard and DOCS_MANUAL_DIR are 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 runs pnpm dev and does not touch the manual, so it needs no guard.

Activity

  1. added a commit that references this issue on Sep 2, 2026
    41401aa
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions