118 lines
5.1 KiB
Markdown
118 lines
5.1 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
rg -n "/home/ray/dev/linkong/planet/docs/technical/(?!zh|en)" docs/technical/zh --pcre2
|
|
```
|
|
|
|
This should return no matches.
|
|
|
|
### Public Docs Registry
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
rg -n "\[[^]]+\.md\]\(" docs/technical/zh docs/technical/en
|
|
```
|
|
|
|
This should return no matches for polished public docs.
|