-
Notifications
You must be signed in to change notification settings - Fork 10
Expand file tree
/
Copy pathbuild_reference.py
More file actions
73 lines (59 loc) · 2.43 KB
/
Copy pathbuild_reference.py
File metadata and controls
73 lines (59 loc) · 2.43 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
"""Generate docs/batch-client-reference.md — a PUBLIC-facing markdown API reference.
Renders each public module with pydoc-markdown, then presents it as the
public import surface (`from zenrows.batch import ...`) rather than where
things physically live:
- the internal module headers (`# zenrows.batch._resources`) become
friendly section titles, and
- the `zenrows.batch._x.` qualifiers are stripped from anchors and inline
references,
so the reference never exposes the private `_module` layout. The modules
stay private on purpose (curated `__all__` re-export from the package) —
this only fixes how the docs are presented.
Run via `make docs` (which supplies pydoc-markdown through `uv --with`).
"""
import re
import subprocess
import sys
# (module, public section title) — order defines the reference layout.
SECTIONS = [
("zenrows.batch.client", "Client"),
("zenrows.batch._resources", "Job, run & export handles"),
("zenrows.batch._waiters", "Waiters"),
("zenrows.batch._download", "Downloads"),
("zenrows.batch._estimate", "Cost estimation"),
("zenrows.batch._schedule", "Schedule builders"),
("zenrows.batch.errors", "Errors"),
("zenrows.batch.models", "Models"),
]
HEADER = (
"# ZenRows Batch — Python SDK Reference\n\n"
"_Auto-generated from the SDK docstrings via `make docs`. Do not edit by "
"hand. Everything below is imported from the top-level `zenrows.batch` "
"package (`from zenrows.batch import ...`)._\n"
)
# Member-qualified references like `zenrows.batch._resources.JobHandle`
# (anchors + inline) → bare `JobHandle` (the public import name).
_QUALIFIER = re.compile(r"zenrows\.batch\.[A-Za-z_][A-Za-z0-9_]*\.")
def render(module: str, title: str) -> str:
out = subprocess.run(
["pydoc-markdown", "-m", module, "-I", "src"],
capture_output=True,
text=True,
check=True,
).stdout
# Drop the leading module anchor + `# zenrows.batch.<mod>` header and put
# the friendly section title in its place.
out = re.sub(
r'\A<a id="' + re.escape(module) + r'"></a>\n\n# [^\n]*\n',
f"# {title}\n",
out,
count=1,
)
# Strip the private/module qualifiers everywhere else.
out = _QUALIFIER.sub("", out)
return out.rstrip() + "\n"
def main() -> None:
parts = [HEADER, *(render(mod, title) for mod, title in SECTIONS)]
sys.stdout.write("\n".join(parts))
if __name__ == "__main__":
main()