chore(docs): the thirteen `docs-*` Makefile targets cannot run in this repository

[rapsealk]

Summary

The docs-* Makefile targets (thirteen, all advertised in make help) cannot run on a checkout of this repository: every input they need (docs/requirements.txt, docs/en/, docs/ko/, docs/shared/, docs/overrides/) is absent, and the two mkdocs configs' nav: blocks list 33 pages each, none of which exist. git log --all -- docs/en is empty, so this is not a deletion regression. A maintainer needs to say whether the manual sources belong in this repo (not landed yet) or are built from a different tree; the fix differs.

Background

Makefile:825-908 defines: docs-install, docs-serve, docs-serve-en, docs-serve-ko, docs-build, docs-build-ko, docs-build-all, docs-build-strict, docs-pdf-setup, docs-pdf-en, docs-pdf-ko, docs-pdf, docs-clean, each with a ## help string.

Required	Referenced from	Present
docs/requirements.txt	Makefile:834 (uv pip install -r docs/requirements.txt)	no
docs/en/	mkdocs.yml:8 (docs_dir: docs/en)	no
docs/ko/	mkdocs.ko.yml:8	no
docs/shared/	mkdocs.yml:75 (snippets include_dir)	no
docs/overrides/	mkdocs.yml:14 (custom_dir)	no

The nav: blocks at mkdocs.yml:128 and mkdocs.ko.yml:131 list 33 page paths each (getting-started/, user-guide/, concepts/, api-reference/, development/, distributed/, index.md, prompt_cache.md); none exist under any docs root. Meanwhile the fifteen real documents in docs/*.md appear in neither nav. docs/README.md:39-41 lists docs/en/... and docs/ko/... under "Expected future layout examples," and mkdocs.yml:3 has site_url: https://mlxcel.lablup.ai/en/manual/, so the configs were written ahead of the content or the manual lives in a tree that is not part of this repo. mkdocs.pdf.yml and mkdocs.ko.pdf.yml inherit the same problem (plus more missing inputs under docs/resources/).

Impact

make help is the discovery surface for the build system and it advertises thirteen targets that fail. make docs-install fails on its first real command with a missing-file error; working around that hits a broken symlink, then an mkdocs run against a nonexistent docs_dir. Nothing says the manual is built elsewhere, so the only way to find out is to run one and read the failure.

Proposed Solution

A maintainer needs to say which situation applies:

(a) The manual sources belong in this repo and have not landed yet. The targets and configs are scaffolding for unwritten content. Add a note to docs/README.md and a guard in docs-install that fails with a clear message ("the manual sources under docs/en are not present in this checkout; see …") instead of an opaque uv pip error.

(b) The manual is built from a different tree (e.g. the private mirror, matching the site_url). The thirteen targets and both mkdocs configs do not belong in the public repository, or must be documented as no-ops here.

Either way, reconcile the 33 dangling nav entries with whatever tree holds the pages, and make the fifteen real docs/*.md files either appear in a nav or be explicitly out of scope.

Implementation Notes

• mkdocs.pdf.yml and mkdocs.ko.pdf.yml have the same problem and should be handled in the same pass.
• The diff is small either way, but it is the wrong change if the (a)/(b) direction is guessed; confirm on the issue first.

Acceptance Criteria

• Running any docs-* target either works, or fails immediately with a message explaining why it cannot work here and where the manual lives.
• make help does not advertise targets that cannot run without saying so.
• The mkdocs navs and the on-disk docs tree agree, or the mismatch is documented.
• No change to the fifteen GitHub-facing documents themselves.

---

Original Suggestion

Title: chore(docs): the twelve docs-* Makefile targets cannot run in this repository

Problem / Background

Makefile:829-906 defines twelve documentation targets, each with a ## help string, so
all twelve appear in make help:

docs-install  docs-serve  docs-serve-en  docs-serve-ko  docs-build  docs-build-ko
docs-build-all  docs-build-strict  docs-pdf-setup  docs-pdf-en  docs-pdf-ko  docs-pdf
docs-clean

None of them can run on a checkout of this repository. Every input they need is absent:

Required	Referenced from	Present
docs/requirements.txt	Makefile:834 (uv pip install -r docs/requirements.txt)	no
docs/en/	mkdocs.yml:8 (docs_dir: docs/en), Makefile:836	no
docs/ko/	mkdocs.ko.yml:8 (docs_dir: docs/ko), Makefile:837	no
docs/shared/	Makefile:836-837 (ln -s ../shared docs/en/shared)	no
docs/overrides/	mkdocs.yml:14, mkdocs.ko.yml:14 (custom_dir)	no

git log --all -- docs/en is empty: this tree has never existed in the repository's
history, so this is not a deletion regression.

On top of that, the nav: blocks in mkdocs.yml:128 and mkdocs.ko.yml:131 list 33
page paths each — getting-started/, user-guide/, concepts/, api-reference/,
development/, distributed/, index.md, prompt_cache.md — and none of the 33 exist
under any docs root in the repo. Meanwhile the fifteen real documents in docs/*.md
(environment-variables.md, CONTINUOUS_BATCHING.md, turbo-kv-cache.md,
responses-api.md, and so on) appear in neither nav.

docs/README.md:41 suggests the intent — it lists docs/en/... and docs/ko/... under
"Expected future layout examples" — so the configs were written ahead of the content, or
the manual sources live in a tree that is not part of this repository.

Impact

make help is the discovery surface for the build system, and it advertises twelve targets
that fail. make docs-install fails on its first real command with a missing-file error
from uv pip; anyone who works around that hits a broken symlink, then an mkdocs run
against a nonexistent docs_dir. There is no note anywhere saying the manual is built
elsewhere, so the only way to find out is to run one and read the failure.

Proposed solution

This needs a maintainer to say which of two situations applies, and the fix differs:

(a) The manual sources belong in this repo and have not landed yet. Then the targets and
the two mkdocs configs are scaffolding for unwritten content. Add a note to docs/README.md
and a guard in docs-install that fails with a clear message ("the manual sources under
docs/en are not present in this checkout; see …") instead of an opaque uv pip error.

(b) The manual is built from a different tree (for example the private mirror, matching
the site_url: https://mlxcel.lablup.ai/en/manual/ in mkdocs.yml:3). Then the twelve
targets and both mkdocs configs do not belong in the public repository at all, or must be
documented as no-ops here.

Either way the 33 dangling nav entries should be reconciled with whatever tree actually
holds the pages, and the fifteen real docs/*.md files should either appear in a nav or be
explicitly out of scope for the site.

Acceptance criteria

• Running any docs-* target either works, or fails immediately with a message
  explaining why it cannot work here and where the manual lives.
• make help does not advertise targets that cannot run without saying so.
• The mkdocs navs and the on-disk docs tree agree, or the mismatch is documented.
• No change to the fifteen GitHub-facing documents themselves.

Technical considerations

mkdocs.pdf.yml and mkdocs.ko.pdf.yml have the same problem and should be handled in the
same pass.

Start by asking on the issue which of (a) or (b) is intended — the diff is small either way,
but it is the wrong change if guessed.

[inureyes]

Decision: case (b), and keep the files

The manual sources (docs/en, docs/ko, docs/shared, docs/requirements.txt, docs/scripts) are maintained in a separate documentation tree, along with that tree's own copies of the four mkdocs configs. They have never existed in this repository's history, which is why git log --all -- docs/en is empty. This is case (b).

The fix is to guard and document rather than delete:

1. The four mkdocs configs stay, unchanged. They belong to the tree that owns the manual and this repository is kept in sync with it, so rewriting their nav: blocks to point at the top-level docs/*.md files here would be both wrong for that tree and undone by the next sync.
2. A shared docs-guard prerequisite that all thirteen docs-* targets depend on. It is a presence check on docs/en, not an unconditional refusal: where the sources exist the targets run exactly as before, and where they do not the build stops with an explanation instead of an opaque uv, symlink, or site-build failure. That keeps one Makefile correct in both trees.
3. A short suffix on each ## help string so make help stops advertising thirteen targets as if they work here.
4. A "The MkDocs manual" section in docs/README.md explaining the split, and pointing readers at the published manual at https://mlxcel.lablup.ai/en/manual/. The docs/en/... and docs/ko/... entries move out of "Expected future layout examples," since they describe the tree that actually holds the manual rather than a future layout here.

The GitHub-facing docs/*.md documents are unchanged, per acceptance criterion 4. They are explicitly out of scope for the manual navs, and that is now stated rather than left to be inferred from a failed build.

One correction to the table in the issue body: docs/overrides/ is not tracked, so it is absent from a fresh clone, but the custom_dir it backs has no content either way. The practical outcome for the build is the same as described.