Documentation Coverage Rules

This file contains Planet-specific documentation coverage rules. Documentation skills and agents should read this file before deciding which docs to update. Keep tool-specific workflow in skills; keep product and repository rules here.

Scope Rules

User-visible workflow changes must update docs/technical/zh/manual.md and usually docs/technical/zh/quickstart.md.
If an English counterpart exists for user-facing docs such as manual.md or quickstart.md, update docs/technical/en/... enough that it does not contradict the Chinese source.
Control console page responsibility changes must update docs/technical/zh/frontend-admin-frontend-context.md.
Earth frontend behavior changes must update docs/technical/zh/earth-frontend-context.md.
Earth layer additions, renderOrder, altitude/radius offsets, depth strategy, pointer picking, legend modes, or layer panel/startup ordering must update docs/technical/zh/earth-render-layer-order.md.
Earth layer visual style or legend symbol/color semantics should also update docs/technical/zh/earth-layer-style-reference.md when that reference is affected.
Collector, datasource, credential, settings, connectivity, scheduler, or API changes must update the relevant backend docs, especially docs/technical/zh/backend-collectors.md and any datasource/settings-specific doc.
When a change turns an old plan assumption into current behavior, update the relevant docs/plans/*.md with a status note instead of leaving contradictory instructions.
Search docs for stale terms introduced by the change, for example old tab names, old route responsibilities, obsolete auth assumptions, or renamed UI labels.

Public Docs Rules

If adding a new technical document, add it to docs/technical/zh/README.md when it should be discoverable from the technical docs index.
If a technical document should be visible in the public Docs page or linked from a technical README, register it in frontend/src/pages/Docs/docs-content.ts under DOCS_METADATA. Files under docs/technical/{zh,en}/ are not automatically routable.
For every public technical doc, keep the bilingual file pair in sync by filename: docs/technical/zh/<name>.md and docs/technical/en/<name>.md. If content is intentionally Chinese-only or English-only, state that intentionally in the final note.
Public docs should use readable link text, not raw filenames such as manual.md.

Credential Collector Rules

Any built-in collector marked requires_credentials: true and credential_status: supported must have:
- a credential_provider in backend/app/core/datasource_defaults.py;
- a default credential guide in backend/app/services/credential_guides.py;
- a supported connectivity provider in backend/app/services/datasource_connectivity.py;
- settings UI guidance or a credential form in frontend/src/pages/Settings/Settings.tsx;
- a regression test that fails if the guide/provider is missing.

Recommended Checks

Run the checks that match the affected docs.

Duplicate Bilingual Docs

python - <<'PY'
from pathlib import Path
same = []
for en in sorted(Path("docs/technical/en").glob("*.md")):
    zh = Path("docs/technical/zh") / en.name
    if zh.exists() and en.read_text() == zh.read_text():
        same.append(en.name)
if same:
    raise SystemExit("identical en/zh docs: " + ", ".join(same))
print("no identical en/zh docs")
PY

Language-Less Technical Links

rg -n "/home/ray/dev/linkong/planet/docs/technical/(?!zh|en)" docs/technical/zh --pcre2

This should return no matches.

Public Docs Registry

python - <<'PY'
import re
from pathlib import Path

metadata = Path("frontend/src/pages/Docs/docs-content.ts").read_text()
known = set(re.findall(r"'([^']+\.md)':\s*\{", metadata))
known.add("README.md")

missing = []
for readme in [Path("docs/technical/zh/README.md"), Path("docs/technical/en/README.md")]:
    if not readme.exists():
        continue
    for href in re.findall(r"\]\(([^)]+\.md)\)", readme.read_text()):
        path = Path(href)
        if "docs/technical/" not in href:
            continue
        filename = path.name
        if filename not in known:
            missing.append(f"{readme}: {filename}")

if missing:
    raise SystemExit("docs README links missing DOCS_METADATA: " + ", ".join(missing))
print("docs README links are whitelisted")
PY

Public Bilingual Pairs

python - <<'PY'
import re
from pathlib import Path

metadata = Path("frontend/src/pages/Docs/docs-content.ts").read_text()
filenames = sorted(set(re.findall(r"'([^']+\.md)':\s*\{", metadata)) - {"README.md"})
missing = []
for filename in filenames:
    for lang in ("zh", "en"):
        path = Path("docs/technical") / lang / filename
        if not path.exists():
            missing.append(str(path))
if missing:
    raise SystemExit("missing bilingual docs: " + ", ".join(missing))
print("public docs have zh/en file pairs")
PY

Raw Filename Link Titles

rg -n "\[[^]]+\.md\]\(" docs/technical/zh docs/technical/en

This should return no matches for polished public docs.

5.1 KiB Raw Blame History