diff --git a/automation/source-repo-templates/api-docs.python.yml b/automation/source-repo-templates/api-docs.python.yml index cfb398c2..0100b60b 100644 --- a/automation/source-repo-templates/api-docs.python.yml +++ b/automation/source-repo-templates/api-docs.python.yml @@ -354,6 +354,110 @@ jobs: ' "$f" > "$f.tmp" && mv "$f.tmp" "$f" done + - name: Cross-link package overview re-export stubs + # pydoc-markdown emits an empty `## ClassName` heading on each + # `/overview.md` for every name re-exported from the + # package's `__init__.py`. The actual class/function bodies + # live on submodule pages (e.g. `models.md`, `tools.md`), so + # the overview's right-side TOC entries lead to dead-end + # in-page anchors with no content. + # + # Replace the empty stub block with a clean `## API` section + # listing each symbol as a link to where it's actually + # defined. Mapping is built by scanning every non-overview + # page for canonical definitions: + # `## ClassName Objects` (h2 + " Objects" suffix) -> class + # `#### function_name` (h4) -> function + # Other heading shapes (h2 without "Objects", h3) are skipped + # because pydoc-markdown reuses them for re-export stubs and + # for class-internal sections respectively. + working-directory: ${{ env.OUTPUT_DIR }} + run: | + python3 - <<'PYINNER' + import pathlib + import re + + root = pathlib.Path(".") + + def slugify(text: str) -> str: + s = text.lower().replace("\\_", "_").replace("\\", "") + s = re.sub(r"[^a-z0-9_\s-]", "", s) + s = re.sub(r"\s+", "-", s.strip()) + return s + + heading_re = re.compile( + r'\n+(#{2,6})\s+([^\n]+?)\n' + ) + + symbol_map: dict[tuple[str, str], tuple[str, str]] = {} + for md in root.rglob("*.md"): + if md.name in ("overview.md", "README.md"): + continue + rel = md.relative_to(root).with_suffix("").as_posix() + text = md.read_text(encoding="utf-8") + for m in heading_re.finditer(text): + full_id = m.group(1) + level = len(m.group(2)) + heading = m.group(3).strip() + parts = full_id.split(".") + if len(parts) < 3: + continue + parent = parts[-2] + # Class members (e.g. `Class.method`) sit under an + # uppercase parent — those are not standalone + # symbols and shouldn't be link targets here. + if parent and parent[0].isupper(): + continue + is_class_def = level == 2 and heading.endswith(" Objects") + is_func_def = level == 4 + if not (is_class_def or is_func_def): + continue + key = (parts[0], parts[-1]) + symbol_map.setdefault(key, (rel, slugify(heading))) + + # An empty stub is `\n\n## Name\n` + # followed by another anchor or end-of-file (no body + # in between). + stub_re = re.compile( + r'\n+##\s+(?P[^\n]+?)\n' + r'(?=\n>> bloom.has("emergency") True - - -## BloomFilter - - - -## CountMinSketch - - - -## Graph - - - -## BoundedHeap - - - -## Trie - - - -## rabin\_karp +## API + +- [`BloomFilter`](./bloom#bloomfilter-objects) +- [`CountMinSketch`](./count_min#countminsketch-objects) +- [`Graph`](./graph#graph-objects) +- [`BoundedHeap`](./heap#boundedheap-objects) +- [`Trie`](./trie#trie-objects) +- [`rabin_karp`](./trie#rabin_karp) diff --git a/sdks/python/api/resq-mcp/overview.md b/sdks/python/api/resq-mcp/overview.md index 6c7dd8ec..9f1602aa 100644 --- a/sdks/python/api/resq-mcp/overview.md +++ b/sdks/python/api/resq-mcp/overview.md @@ -14,130 +14,37 @@ This package provides: from resq_mcp import mcp mcp.run() - - -## annotations - - - -## Settings - - - -## settings - - - -## Coordinates - - - -## DetectedObject - - - -## DisasterScenario - - - -## ErrorResponse - - - -## Sector - - - -## DeploymentRequest - - - -## DeploymentStatus - - - -## NetworkStatus - - - -## SectorAnalysis - - - -## SectorStatusSummary - - - -## SwarmStatus - - - -## get\_all\_sectors\_status - - - -## get\_drone\_swarm\_status - - - -## request\_drone\_deployment - - - -## scan\_current\_sector - - - -## OptimizationStrategy - - - -## SimulationRequest - - - -## get\_optimization\_strategy - - - -## run\_simulation - - - -## IncidentReport - - - -## IncidentValidation - - - -## MissionParameters - - - -## update\_mission\_params - - - -## validate\_incident - - - -## PreAlert - - - -## VulnerabilityMap - - - -## get\_predictive\_alerts - - - -## get\_vulnerability\_map - - - -## mcp +## API + +- `annotations` +- [`Settings`](./core/config#settings-objects) +- [`settings`](./core/config#settings) +- [`Coordinates`](./models#coordinates-objects) +- [`DetectedObject`](./models#detectedobject-objects) +- [`DisasterScenario`](./models#disasterscenario-objects) +- [`ErrorResponse`](./models#errorresponse-objects) +- [`Sector`](./models#sector-objects) +- [`DeploymentRequest`](./models#deploymentrequest-objects) +- [`DeploymentStatus`](./models#deploymentstatus-objects) +- [`NetworkStatus`](./models#networkstatus-objects) +- [`SectorAnalysis`](./models#sectoranalysis-objects) +- [`SectorStatusSummary`](./models#sectorstatussummary-objects) +- [`SwarmStatus`](./models#swarmstatus-objects) +- [`get_all_sectors_status`](./tools#get_all_sectors_status) +- [`get_drone_swarm_status`](./tools#get_drone_swarm_status) +- [`request_drone_deployment`](./tools#request_drone_deployment) +- [`scan_current_sector`](./tools#scan_current_sector) +- [`OptimizationStrategy`](./models#optimizationstrategy-objects) +- [`SimulationRequest`](./models#simulationrequest-objects) +- [`get_optimization_strategy`](./dtsop/service#get_optimization_strategy) +- [`run_simulation`](./dtsop/tools#run_simulation) +- [`IncidentReport`](./models#incidentreport-objects) +- [`IncidentValidation`](./models#incidentvalidation-objects) +- [`MissionParameters`](./models#missionparameters-objects) +- [`update_mission_params`](./hce/tools#update_mission_params) +- [`validate_incident`](./hce/tools#validate_incident) +- [`PreAlert`](./models#prealert-objects) +- [`VulnerabilityMap`](./models#vulnerabilitymap-objects) +- [`get_predictive_alerts`](./pdie/service#get_predictive_alerts) +- [`get_vulnerability_map`](./pdie/service#get_vulnerability_map) +- [`mcp`](./server#mcp)