pubdocrules 0.5.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. pubdoc/__init__.py +1 -0
  2. pubdoc/__main__.py +5 -0
  3. pubdoc/cli.py +800 -0
  4. pubdoc/compare.py +121 -0
  5. pubdoc/corpus.py +245 -0
  6. pubdoc/fonts/DejaVuSans-Bold.ttf +0 -0
  7. pubdoc/fonts/DejaVuSans.ttf +0 -0
  8. pubdoc/fonts/LICENCE-Ubuntu.txt +96 -0
  9. pubdoc/fonts/LICENSE-DejaVu.txt +78 -0
  10. pubdoc/fonts/LICENSE-Liberation.txt +130 -0
  11. pubdoc/fonts/LiberationSans-Bold.ttf +0 -0
  12. pubdoc/fonts/LiberationSans-BoldItalic.ttf +0 -0
  13. pubdoc/fonts/LiberationSans-Italic.ttf +0 -0
  14. pubdoc/fonts/LiberationSans-Regular.ttf +0 -0
  15. pubdoc/fonts/README.md +21 -0
  16. pubdoc/fonts/Ubuntu-R.ttf +0 -0
  17. pubdoc/projects.py +501 -0
  18. pubdoc/registry.py +54 -0
  19. pubdoc/schema/doc.schema.json +14 -0
  20. pubdoc/schema/project.schema.json +142 -0
  21. pubdoc/schema/pubdoc.schema.json +16 -0
  22. pubdoc/settings.py +66 -0
  23. pubdoc/storage.py +126 -0
  24. pubdoc/templates/annotations.mjs +116 -0
  25. pubdoc/templates/charged-ieee/template.typ +41 -0
  26. pubdoc/templates/charged-ieee/template.yml +28 -0
  27. pubdoc/templates/cv-sidebar/cv-sidebar.typ +113 -0
  28. pubdoc/templates/cv-sidebar/template.typ +11 -0
  29. pubdoc/templates/cv-sidebar/template.yml +23 -0
  30. pubdoc/templates/lapreprint-typst/LICENSE +21 -0
  31. pubdoc/templates/lapreprint-typst/frontmatter.typ +244 -0
  32. pubdoc/templates/lapreprint-typst/lapreprint.typ +314 -0
  33. pubdoc/templates/lapreprint-typst/template.typ +112 -0
  34. pubdoc/templates/lapreprint-typst/template.yml +82 -0
  35. pubdoc/templates/linkedin-text.mjs +127 -0
  36. pubdoc/templates/pub-plugin.mjs +117 -0
  37. pubdoc/versions.py +383 -0
  38. pubdocrules-0.5.0.dist-info/METADATA +355 -0
  39. pubdocrules-0.5.0.dist-info/RECORD +43 -0
  40. pubdocrules-0.5.0.dist-info/WHEEL +5 -0
  41. pubdocrules-0.5.0.dist-info/entry_points.txt +2 -0
  42. pubdocrules-0.5.0.dist-info/licenses/LICENSE +202 -0
  43. pubdocrules-0.5.0.dist-info/top_level.txt +1 -0
pubdoc/cli.py ADDED
@@ -0,0 +1,800 @@
1
+ """pubdoc's command line: check, build, preview and approve the document projects in a repo.
2
+
3
+ A document project is a directory holding a project.yml, anywhere in a
4
+ repository; each doc in it is a directory of MyST parts beside that file
5
+ (projects.py says how). `build` stages a doc's parts and the shared parts
6
+ they start from in the doc's build/, writes the MyST configuration for
7
+ every variant and layout there from project.yml, runs the pinned
8
+ Curvenote, then `typst compile` on each Typst export, and runs each
9
+ exporter layout. Everything it writes stays in the doc's build/, which
10
+ ignores itself.
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ import argparse
16
+ import datetime
17
+ import os
18
+ import re
19
+ import shutil
20
+ import subprocess
21
+ import sys
22
+ import tempfile
23
+ from importlib import metadata, resources
24
+ from pathlib import Path
25
+
26
+ import yaml
27
+
28
+ from . import compare, corpus, projects, registry, settings, storage, versions
29
+ from .projects import BUILD, VERSIONS, Doc, Problem, Project, Render
30
+
31
+ CURVENOTE_VERSION = "0.17.2"
32
+ LAUNCHER = "pubdoc"
33
+ # The distribution: PyPI's "pubdoc" is another project, so pubdoc's is
34
+ # pubdocrules. The package, the command and the repository stay pubdoc.
35
+ DISTRIBUTION = "pubdocrules"
36
+ WHEEL_URL = "https://github.com/Sustenaut/pubdoc/releases/download/v{version}/pubdocrules-{version}-py3-none-any.whl"
37
+ # The launcher's pin, one requirement line beside it, where pubrules's nightly
38
+ # moves it to pubdoc's latest release like any other release wheel pin.
39
+ PIN = "requirements-pubdoc.txt"
40
+ # Inside a doc's build/: pubdoc's templates, and the staged sources Curvenote builds.
41
+ TEMPLATES, SOURCES = "templates", "src"
42
+ IGNORE_ALL = "# Written by pubdoc: everything here is built, never committed.\n*\n"
43
+
44
+
45
+ def version() -> str:
46
+ try:
47
+ return metadata.version(DISTRIBUTION)
48
+ except metadata.PackageNotFoundError: # a checkout run without installing
49
+ return "0+unknown"
50
+
51
+
52
+ def die(message: str, code: int = 1) -> None:
53
+ print(f"pubdoc: {message}", file=sys.stderr)
54
+ sys.exit(code)
55
+
56
+
57
+ def resolve_typst() -> str:
58
+ """typst on PATH, else a local build at ~/git/typst. Curvenote runs typst
59
+ itself too, so its directory goes onto PATH for child processes."""
60
+ found = shutil.which("typst")
61
+ local = Path.home() / "git/typst/target/release/typst"
62
+ if not found and os.access(local, os.X_OK):
63
+ found = str(local)
64
+ if not found:
65
+ die("no 'typst' on PATH and no build at ~/git/typst/target/release/typst.\n"
66
+ "Install typst (https://typst.app), or build it from ~/git/typst:\n"
67
+ " cargo build --release -p typst-cli --features typst-kit/vendor-openssl")
68
+ os.environ["PATH"] = f"{Path(found).parent}{os.pathsep}{os.environ.get('PATH', '')}"
69
+ return found
70
+
71
+
72
+ def need(program: str, hint: str) -> str:
73
+ found = shutil.which(program)
74
+ if not found:
75
+ die(f"no '{program}' on PATH; {hint}")
76
+ return found
77
+
78
+
79
+ def write_if_changed(path: Path, data: bytes) -> None:
80
+ """Rewrite only a file that differs, so a running preview sees no churn."""
81
+ if not path.is_file() or path.read_bytes() != data:
82
+ path.parent.mkdir(parents=True, exist_ok=True)
83
+ path.write_bytes(data)
84
+
85
+
86
+ def mirror(wanted: dict[Path, bytes], target: Path) -> Path:
87
+ """Make `target` hold exactly `wanted`, rewriting only the files that differ."""
88
+ for rel, data in wanted.items():
89
+ write_if_changed(target / rel, data)
90
+ if target.is_dir():
91
+ for path in sorted(target.rglob("*"), reverse=True):
92
+ rel = path.relative_to(target)
93
+ if (path.is_file() or path.is_symlink()) and rel not in wanted:
94
+ path.unlink()
95
+ elif path.is_dir() and not any(path.iterdir()):
96
+ path.rmdir()
97
+ return target
98
+
99
+
100
+ def install_templates(target: Path) -> Path:
101
+ """Make `target` hold exactly this release's templates and plugins."""
102
+ wanted: dict[Path, bytes] = {}
103
+ stack = [(resources.files("pubdoc") / "templates", Path())]
104
+ while stack:
105
+ node, prefix = stack.pop()
106
+ for child in node.iterdir():
107
+ if child.is_dir():
108
+ stack.append((child, prefix / child.name))
109
+ else:
110
+ wanted[prefix / child.name] = child.read_bytes()
111
+ return mirror(wanted, target)
112
+
113
+
114
+ def curvenote(*args: str) -> list[str]:
115
+ return [need("npx", "install Node.js (https://nodejs.org)"), "--yes",
116
+ f"curvenote@{CURVENOTE_VERSION}", *args]
117
+
118
+
119
+ # Projects and docs -------------------------------------------------------
120
+
121
+ def report(problems: list[Problem]) -> None:
122
+ for problem in problems:
123
+ print(f"pubdoc: {problem}", file=sys.stderr)
124
+
125
+
126
+ def load_checked(file: Path) -> tuple[Project | None, list[Problem], list[str]]:
127
+ problems: list[Problem] = []
128
+ project = projects.load(file, problems)
129
+ notes: list[str] = []
130
+ if project:
131
+ found, notes = projects.check(project)
132
+ problems.extend(found)
133
+ return project, problems, notes
134
+
135
+
136
+ def project_or_die(file: Path) -> Project:
137
+ project, problems, _ = load_checked(file)
138
+ if problems or not project:
139
+ report(problems)
140
+ die(f"{projects.shown(file)} has {len(problems)} problem(s); see `pubdoc check`")
141
+ return project
142
+
143
+
144
+ def target(name: str) -> tuple[Project, list[Doc]]:
145
+ """A project directory (all its docs) or one doc directory of it."""
146
+ path = Path(name).resolve()
147
+ if (path / projects.PROJECT_FILE).is_file():
148
+ project = project_or_die(path / projects.PROJECT_FILE)
149
+ if not project.docs:
150
+ die(f"{name} has no docs")
151
+ return project, project.docs
152
+ if (path.parent / projects.PROJECT_FILE).is_file():
153
+ project = project_or_die(path.parent / projects.PROJECT_FILE)
154
+ for doc in project.docs:
155
+ if doc.path == path:
156
+ return project, [doc]
157
+ die(f"{name} is no doc of {projects.shown(project.path)}: it holds no doc.yml and no part file")
158
+ die(f"{name} is not a doc or a project: no project.yml in it or the directory above")
159
+ raise AssertionError # pragma: no cover - die exits
160
+
161
+
162
+ def one_doc(name: str) -> Doc:
163
+ _, docs = target(name)
164
+ if len(docs) != 1:
165
+ die(f"{name} is a project; name one of its docs: {', '.join(d.label for d in docs)}")
166
+ return docs[0]
167
+
168
+
169
+ def pick(doc: Doc, variant: str | None, layout: str | None) -> Render:
170
+ """The PDF render named, or the doc's only one where a choice is left out."""
171
+ renders = [r for r in doc.renders(variant, layout) if r.spec["format"] == "pdf"]
172
+ if len(renders) == 1:
173
+ return renders[0]
174
+ if not renders:
175
+ die(f"{doc.label} has no PDF layout for {variant or 'any variant'} and {layout or 'any layout'}")
176
+ choices = sorted({f"{r.variant} {r.layout}" for r in renders})
177
+ die(f"{doc.label} has {len(renders)} PDF renders ({', '.join(choices)}); name the variant and layout")
178
+ raise AssertionError # pragma: no cover - die exits
179
+
180
+
181
+ # Commands ----------------------------------------------------------------
182
+
183
+ def cmd_check(args: argparse.Namespace) -> int:
184
+ start = Path(args.path)
185
+ if not start.exists():
186
+ die(f"{args.path} does not exist")
187
+ files = projects.find(start)
188
+ if not files:
189
+ die(f"no project.yml in {args.path} or below it")
190
+ problems: list[Problem] = []
191
+ notes: set[str] = set()
192
+ docs = 0
193
+ roots = set()
194
+ for file in files:
195
+ project, found, said = load_checked(file)
196
+ problems.extend(found)
197
+ notes.update(said)
198
+ docs += len(project.docs) if project else 0
199
+ roots.add(projects.repo_root(file.parent).resolve())
200
+ for root in sorted(roots):
201
+ settings.root_config(root, problems)
202
+ for note in sorted(notes):
203
+ print(f"note: {note}")
204
+ if problems:
205
+ report(problems)
206
+ print(f"{len(problems)} problem(s) in {len(files)} project(s)", file=sys.stderr)
207
+ return 1
208
+ print(f"checked {len(files)} project(s) with {docs} doc(s): no problems")
209
+ return 0
210
+
211
+
212
+ def cmd_list(args: argparse.Namespace) -> int:
213
+ for file in projects.find(Path(args.path)):
214
+ problems: list[Problem] = []
215
+ project = projects.load(file, problems)
216
+ if not project:
217
+ print(f"{projects.shown(file.parent)}: does not load; see `pubdoc check`")
218
+ continue
219
+ print(f"{projects.shown(project.path)}: {project.config['purpose']}")
220
+ for doc in project.docs:
221
+ print(f" {doc.label} ({', '.join(doc.variants())})")
222
+ return 0
223
+
224
+
225
+ def cmd_variants(args: argparse.Namespace) -> int:
226
+ for variant in one_doc(args.name).variants():
227
+ print(variant)
228
+ return 0
229
+
230
+
231
+ def doc_files(doc: Doc) -> dict[Path, bytes]:
232
+ """The doc's files and those of the shared parts it starts from, by
233
+ their path in the project, so a part's MyST include of ../shared/...
234
+ resolves the same when staged."""
235
+ project = doc.project
236
+ wanted: dict[Path, bytes] = {}
237
+ sources = [doc.path] + sorted({project.shared_dir(part) for part in project.config["parts"]
238
+ if project.shared_dir(part)})
239
+ for source in sources:
240
+ if not source.is_dir():
241
+ continue
242
+ rel = source.relative_to(project.path)
243
+ for here, dirs, files in os.walk(source):
244
+ dirs[:] = [d for d in dirs if not (Path(here) == doc.path and d in (BUILD, VERSIONS))
245
+ and not d.startswith(".")]
246
+ for f in files:
247
+ path = Path(here) / f
248
+ wanted[rel / path.relative_to(source)] = path.read_bytes()
249
+ return wanted
250
+
251
+
252
+ def fonts() -> Path:
253
+ """The fonts pubdoc carries (fonts/README.md): typst sees these alone."""
254
+ return Path(str(resources.files("pubdoc") / "fonts"))
255
+
256
+
257
+ def typst_fonts() -> list[str]:
258
+ return ["--ignore-system-fonts", "--font-path", str(fonts())]
259
+
260
+
261
+ def myst_config(doc: Doc, root: Path, toc: list[Path], renders: list[Render],
262
+ date: str | None = None) -> bytes:
263
+ """A myst.yml in `root` whose table of contents is `toc` and which
264
+ exports each render. An export through the table of contents, not one
265
+ naming its `article:`, nests a part's headings under its title (# is a
266
+ level-2 heading), as the templates expect."""
267
+ templates = os.path.relpath(doc.path / BUILD / TEMPLATES, root)
268
+ plugins = [str(Path(templates) / "annotations.mjs")]
269
+ # pub-plugin.mjs needs the repository's publets-local.json, found upwards.
270
+ if any((d / "publets-local.json").is_file() for d in [doc.path, *doc.path.parents]):
271
+ plugins.insert(0, str(Path(templates) / "pub-plugin.mjs"))
272
+ exports = [{"format": "typst",
273
+ "template": (os.path.relpath(local, root)
274
+ if (local := doc.project.template_dir(r.spec["template"]))
275
+ else str(Path(templates) / r.spec["template"])),
276
+ "output": os.path.relpath(r.typst_source, root)}
277
+ for r in renders]
278
+ project = {"plugins": plugins, "toc": [{"file": str(f)} for f in toc], "exports": exports}
279
+ if date:
280
+ # The doc's date, which a template prints, unless a part sets its own.
281
+ project["date"] = date
282
+ myst = {"version": 1, "project": project, "site": {"nav": []}}
283
+ return ("# Written by pubdoc from project.yml: do not edit.\n"
284
+ + yaml.safe_dump(myst, sort_keys=False)).encode()
285
+
286
+
287
+ def stage(doc: Doc, renders: list[Render], date: str | None = None) -> dict[Path, list[Render]]:
288
+ """Stage one MyST project per part file the Typst renders use, in
289
+ build/src/<file>/, each holding the doc's files and its shared parts and
290
+ a myst.yml whose table of contents is that one file. Curvenote builds a
291
+ project's exports from its table of contents, so a project per file is
292
+ what lets each render take its own variant of a part."""
293
+ files = doc_files(doc)
294
+ src = doc.path / BUILD / SOURCES
295
+ groups: dict[Path, list[Render]] = {}
296
+ for r in renders:
297
+ if "template" in r.spec:
298
+ groups.setdefault(r.source.relative_to(doc.project.path), []).append(r)
299
+ wanted: dict[Path, bytes] = {}
300
+ staged: dict[Path, list[Render]] = {}
301
+ for article, group in groups.items():
302
+ name = Path(".".join(article.with_suffix("").parts))
303
+ for rel, data in files.items():
304
+ wanted[name / rel] = data
305
+ wanted[name / "myst.yml"] = myst_config(doc, src / name, [article], group, date)
306
+ staged[src / name] = group
307
+ mirror(wanted, src)
308
+ return staged
309
+
310
+
311
+ def stage_site(doc: Doc) -> Path:
312
+ """One MyST project of every part file the doc's renders use, for a live site."""
313
+ site = doc.path / BUILD / "site"
314
+ wanted = doc_files(doc)
315
+ toc = sorted({r.source.relative_to(doc.project.path) for r in doc.renders()})
316
+ wanted[Path("myst.yml")] = myst_config(doc, site, toc, [])
317
+ return mirror(wanted, site)
318
+
319
+
320
+ def prepare(doc: Doc) -> Path:
321
+ out = doc.path / BUILD
322
+ write_if_changed(out / ".gitignore", IGNORE_ALL.encode())
323
+ return install_templates(out / TEMPLATES)
324
+
325
+
326
+ def build(doc: Doc, typst: str, variant: str | None = None, layout: str | None = None,
327
+ timestamp: int | None = None, date: str | None = None) -> str | None:
328
+ """Build every render of `doc`, or those named: None when all were
329
+ built, else why one was not. With `timestamp`, each PDF says it was made
330
+ then, so the same sources and tools make the same bytes."""
331
+ renders = doc.renders(variant, layout)
332
+ if not renders:
333
+ return f"{doc.label} has nothing to build for {variant or 'any variant'} and {layout or 'any layout'}"
334
+ templates = prepare(doc)
335
+ for src, group in stage(doc, renders, date).items():
336
+ if subprocess.call(curvenote("build", "--typst"), cwd=src) != 0:
337
+ return f"curvenote build failed for {doc.label}"
338
+ for r in group:
339
+ typ = r.typst_source
340
+ stamp = ["--creation-timestamp", str(timestamp)] if timestamp is not None else []
341
+ if subprocess.call([typst, "compile", *typst_fonts(), *stamp, str(typ), str(r.output)]) != 0:
342
+ return f"typst compile failed for {typ}"
343
+ print(f"built {projects.shown(r.output)}")
344
+ for r in renders:
345
+ if r.spec.get("exporter") == "linkedin":
346
+ node = need("node", "install Node.js (https://nodejs.org)")
347
+ r.output.parent.mkdir(parents=True, exist_ok=True)
348
+ with r.output.open("w", encoding="utf-8") as out:
349
+ # In the doc's directory, so pub-plugin.mjs finds the repo's publets.
350
+ if subprocess.call([node, str(templates / "linkedin-text.mjs"), str(r.source)],
351
+ cwd=doc.path, stdout=out) != 0:
352
+ return f"the linkedin exporter failed for {r.source}"
353
+ print(f"built {projects.shown(r.output)}")
354
+ return None
355
+
356
+
357
+ def cmd_build(args: argparse.Namespace) -> int:
358
+ if args.all == (args.name is not None):
359
+ die("build takes a doc or a project, or --all for every doc here", 2)
360
+ if args.all:
361
+ return build_all()
362
+ _, docs = target(args.name)
363
+ if (args.variant or args.layout) and len(docs) != 1:
364
+ die("--variant and --layout need one doc")
365
+ typst = resolve_typst()
366
+ timestamp = None
367
+ if args.date:
368
+ try:
369
+ timestamp = versions.Approval("", args.date, "", "", "").timestamp
370
+ except ValueError:
371
+ die(f"--date {args.date} is not a date, YYYY-MM-DD", 2)
372
+ for doc in docs:
373
+ if failure := build(doc, typst, args.variant, args.layout, timestamp=timestamp, date=args.date):
374
+ die(failure)
375
+ return 0
376
+
377
+
378
+ def build_all() -> int:
379
+ """Build every doc of every project here, going on past a failure so
380
+ one run reports them all."""
381
+ files = projects.find(projects.repo_root(Path.cwd()))
382
+ if not files:
383
+ die("no projects here: no project.yml in this repository")
384
+ typst = resolve_typst()
385
+ total, failed = 0, []
386
+ for file in files:
387
+ project, problems, _ = load_checked(file)
388
+ if problems or not project:
389
+ report(problems)
390
+ total += 1
391
+ failed.append(f"{projects.shown(file.parent)} (does not check)")
392
+ continue
393
+ for doc in project.docs:
394
+ total += 1
395
+ if failure := build(doc, typst):
396
+ print(f"pubdoc: {failure}", file=sys.stderr)
397
+ failed.append(doc.label)
398
+ print(f"built {total - len(failed)} of {total} docs"
399
+ + (f"; failed: {', '.join(failed)}" if failed else ""))
400
+ return 1 if failed else 0
401
+
402
+
403
+ def cmd_open(args: argparse.Namespace) -> int:
404
+ doc = one_doc(args.name)
405
+ resolve_typst()
406
+ prepare(doc)
407
+ src = stage_site(doc)
408
+ port = ["--port", args.port] if args.port else []
409
+ os.chdir(src)
410
+ command = curvenote("start", *port)
411
+ os.execv(command[0], command)
412
+ return 0 # pragma: no cover - execv does not return
413
+
414
+
415
+ def review_config(r: Render) -> dict:
416
+ """review-builder's configuration for one render. Its Accept button runs
417
+ approve, which prints the approved render's address in storage."""
418
+ doc, out = r.doc, r.doc.path / BUILD
419
+ watched = [f for d in [doc.path] + [doc.project.shared_dir(p) for p in doc.project.config["parts"]]
420
+ if d and d.is_dir() for f in sorted(d.iterdir())
421
+ if f.is_file() and f.suffix in (".md", ".yml", ".bib")]
422
+ watched.append(doc.project.file)
423
+ pubdoc = [sys.executable, "-m", "pubdoc"]
424
+ return {
425
+ "title": f"{doc.label}: {r.variant} {r.layout}",
426
+ "watched_files": [os.path.relpath(f, out) for f in watched],
427
+ "build_cmd": [*pubdoc, "build", str(doc.path), "--variant", r.variant, "--layout", r.layout],
428
+ "pdf_path": str(r.output.relative_to(out)),
429
+ "preview_dirname": str(Path("preview") / r.variant / r.layout),
430
+ "commit_cmd": [*pubdoc, "approve", str(doc.path), "--variant", r.variant, "--show", r.layout],
431
+ }
432
+
433
+
434
+ def cmd_preview(args: argparse.Namespace) -> int:
435
+ r = pick(one_doc(args.name), args.variant, args.layout)
436
+ out = r.doc.path / BUILD
437
+ out.mkdir(exist_ok=True)
438
+ write_if_changed(out / ".gitignore", IGNORE_ALL.encode())
439
+ write_if_changed(out / "review-builder.yaml",
440
+ ("# Written by pubdoc preview: do not edit.\n"
441
+ + yaml.safe_dump(review_config(r), sort_keys=False)).encode())
442
+ preview = need("review-builder-preview", "install review-builder: pipx install ~/git/review-builder")
443
+ os.chdir(out)
444
+ os.execv(preview, [preview, *([args.port] if args.port else [])])
445
+ return 0 # pragma: no cover - execv does not return
446
+
447
+
448
+ def git(where: Path, *args: str) -> str:
449
+ done = subprocess.run(["git", "-C", str(where), *args], capture_output=True, text=True)
450
+ if done.returncode != 0:
451
+ die(f"git {' '.join(args)} failed: {done.stderr.strip()}")
452
+ return done.stdout.strip()
453
+
454
+
455
+ def approver(doc: Doc) -> str:
456
+ """Who approves: $PUBDOC_APPROVER, else the GitHub login gh is signed in
457
+ as. When the project names reviewers, it must be one of them."""
458
+ who = os.environ.get("PUBDOC_APPROVER")
459
+ if not who and shutil.which("gh"):
460
+ done = subprocess.run(["gh", "api", "user", "--jq", ".login"], capture_output=True, text=True)
461
+ who = done.stdout.strip() if done.returncode == 0 else None
462
+ if not who:
463
+ die("cannot tell who approves: sign in with `gh auth login`, or set PUBDOC_APPROVER")
464
+ reviewers = doc.project.config.get("roles", {}).get("reviewers")
465
+ if reviewers and who not in reviewers:
466
+ die(f"{who} is not one of {projects.shown(doc.project.file)}'s reviewers ({', '.join(reviewers)})")
467
+ return who
468
+
469
+
470
+ def cmd_approve(args: argparse.Namespace) -> int:
471
+ """Build, upload, sign and record a version of each variant asked for."""
472
+ doc = one_doc(args.name)
473
+ variants = [args.variant] if args.variant else doc.variants()
474
+ for v in variants:
475
+ if v not in doc.variants():
476
+ die(f"{doc.label} has no variant {v} ({', '.join(doc.variants())})")
477
+ conf = settings.of(doc.project)
478
+ root = conf.root
479
+ if not args.allow_dirty:
480
+ dirty = git(root, "status", "--porcelain", "--untracked-files=all", "--",
481
+ str(doc.project.path), str(conf.corpus))
482
+ if dirty:
483
+ die(f"commit these first, so the version names the sources it was built from:\n{dirty}")
484
+ for step in doc.review():
485
+ for checker in step.get("automatic", []):
486
+ if checker != "build" and not registry.CHECKERS[checker].implemented:
487
+ print(f"note: checker {checker!r} is not implemented yet; approving without it")
488
+ date = args.date or datetime.date.today().isoformat()
489
+ approval = versions.Approval(approver=approver(doc), date=date, commit=git(root, "rev-parse", "HEAD"),
490
+ rebuilt_from=args.rebuilt_from or "", pubdoc=version())
491
+ typst = resolve_typst()
492
+ shown = None
493
+ for v in variants:
494
+ renders = doc.renders(v)
495
+ if failure := build(doc, typst, v, timestamp=approval.timestamp, date=approval.date):
496
+ die(failure)
497
+ try:
498
+ entry = versions.publish(doc, v, approval, renders, doc_files(doc))
499
+ except (versions.VersionError, storage.StorageError) as e:
500
+ die(str(e))
501
+ print(f"approved version {entry['version']} of {doc.label} ({v}): {entry['publet']}")
502
+ for layout, render in entry["renders"].items():
503
+ print(f" {layout}: {render['url']}")
504
+ if layout == args.show or (shown is None and not args.show):
505
+ shown = render["url"]
506
+ print(f"commit {projects.shown(versions.index_path(doc))} and {projects.shown(conf.corpus)}")
507
+ # review-builder's Accept button links to the last line printed.
508
+ if shown:
509
+ print(shown)
510
+ return 0
511
+
512
+
513
+ def cmd_versions(args: argparse.Namespace) -> int:
514
+ doc = one_doc(args.name)
515
+ index = versions.read_index(doc)
516
+ if not index["versions"]:
517
+ print(f"{doc.label} has no versions yet")
518
+ return 0
519
+ for entry in index["versions"]:
520
+ rebuilt = f", rebuilt from {entry['rebuilt_from']}" if entry.get("rebuilt_from") else ""
521
+ print(f"{entry['variant']} v{entry['version']} {entry['approved']} by {entry['approved_by']}"
522
+ f" {entry['publet']}{rebuilt}")
523
+ for layout, render in entry["renders"].items():
524
+ print(f" {layout}: {render['url']}")
525
+ return 0
526
+
527
+
528
+ def cmd_fetch(args: argparse.Namespace) -> int:
529
+ doc = one_doc(args.name)
530
+ entries = [e for e in versions.read_index(doc)["versions"]
531
+ if (not args.variant or e["variant"] == args.variant)
532
+ and (args.version is None or int(e["version"]) == args.version)]
533
+ if not entries:
534
+ die(f"{doc.label} has no such version")
535
+ entry = entries[0]
536
+ layouts = [args.layout] if args.layout else list(entry["renders"])
537
+ out = Path(args.out)
538
+ out.mkdir(parents=True, exist_ok=True)
539
+ for layout in layouts:
540
+ render = entry["renders"].get(layout)
541
+ if not render:
542
+ die(f"version {entry['version']} of {doc.label} has no {layout} render "
543
+ f"({', '.join(entry['renders'])})")
544
+ name = Path(render["url"]).name
545
+ try:
546
+ target = storage.save(render["url"], render["sha256"],
547
+ versions.tenant_base(settings.of(doc.project)), out / name)
548
+ except storage.StorageError as e:
549
+ die(str(e))
550
+ print(target)
551
+ return 0
552
+
553
+
554
+ def cmd_verify(args: argparse.Namespace) -> int:
555
+ files = projects.find(Path(args.path))
556
+ problems, checked, corpora, seen = [], 0, set(), []
557
+ for file in files:
558
+ project, found, _ = load_checked(file)
559
+ if not project:
560
+ problems.extend(str(p) for p in found)
561
+ continue
562
+ seen.append(project)
563
+ for doc in project.docs:
564
+ if not versions.index_path(doc).is_file():
565
+ continue
566
+ corpus = settings.of(project).corpus
567
+ try:
568
+ if corpus not in corpora:
569
+ versions.verify_corpus(corpus)
570
+ corpora.add(corpus)
571
+ problems.extend(versions.verify_doc(doc, args.remote))
572
+ except versions.VersionError as e:
573
+ problems.append(f"{doc.label}: {e}")
574
+ checked += 1
575
+ for corpus in sorted(corpora):
576
+ signer = versions.lock(corpus).get("corpus", {}).get("key")
577
+ trusted = next((settings.of(p).key for p in seen if settings.of(p).corpus == corpus), None)
578
+ if not trusted:
579
+ print(f"note: {projects.shown(corpus)} is signed by {signer}; no corpus.key names the key "
580
+ "to trust, so that one is accepted")
581
+ notes = [p for p in problems if p.startswith("note: ")]
582
+ problems = [p for p in problems if not p.startswith("note: ")]
583
+ for note in notes:
584
+ print(note)
585
+ for problem in problems:
586
+ print(f"pubdoc: {problem}", file=sys.stderr)
587
+ if problems:
588
+ return 1
589
+ print(f"verified {checked} doc(s)' versions against {len(corpora)} signed corpus(es)"
590
+ + (", and every render in storage" if args.remote else ""))
591
+ return 0
592
+
593
+
594
+ def cmd_corpus(args: argparse.Namespace) -> int:
595
+ project = None
596
+ if args.project:
597
+ file = Path(args.project) / projects.PROJECT_FILE
598
+ if not file.is_file():
599
+ die(f"{args.project} is not a project: it holds no {projects.PROJECT_FILE}")
600
+ project = project_or_die(file)
601
+ root = projects.repo_root(project.path).resolve()
602
+ else:
603
+ root = projects.repo_root(Path.cwd()).resolve()
604
+ try:
605
+ done = corpus.init(project, root, args.backup_name, args.bitwarden_project, not args.no_backup)
606
+ except (corpus.CorpusError, versions.VersionError) as e:
607
+ die(str(e))
608
+ for line in done or ["nothing to do: the corpus, its key and its backup are in place"]:
609
+ print(line)
610
+ print("commit the corpus's corpus.json and the config naming its key, if either changed")
611
+ return 0
612
+
613
+
614
+ def cmd_compare(args: argparse.Namespace) -> int:
615
+ try:
616
+ report = compare.compare(Path(args.first), Path(args.second))
617
+ except compare.CompareError as e:
618
+ die(str(e))
619
+ for line in report.lines():
620
+ print(line)
621
+ return 0 if report.same else 1
622
+
623
+
624
+ def cmd_linkedin(args: argparse.Namespace) -> int:
625
+ source = Path(args.index)
626
+ if not source.is_file():
627
+ die(f"{args.index} does not exist")
628
+ node = need("node", "install Node.js (https://nodejs.org)")
629
+ with tempfile.TemporaryDirectory(prefix="pubdoc-") as scratch:
630
+ script = install_templates(Path(scratch)) / "linkedin-text.mjs"
631
+ return subprocess.call([node, str(script), str(source)])
632
+
633
+
634
+ NEW_PROJECT = """\
635
+ # A document project: see https://github.com/Sustenaut/pubdoc#document-projects
636
+ project: {name}
637
+ purpose: {purpose}
638
+ parts:
639
+ main: {{required: true}}
640
+ variants:
641
+ default: {{audience: Everyone}}
642
+ layouts:
643
+ main-pdf: {{part: main, template: lapreprint-typst, format: pdf}}
644
+ review:
645
+ - step: checks
646
+ automatic: [build]
647
+ """
648
+
649
+ NEW_DOC = """\
650
+ ---
651
+ title: {name}
652
+ ---
653
+
654
+ # Introduction
655
+
656
+ Write here.
657
+ """
658
+
659
+
660
+ def cmd_new_project(args: argparse.Namespace) -> int:
661
+ path = Path(args.path)
662
+ name = path.resolve().name
663
+ if (path / projects.PROJECT_FILE).exists():
664
+ die(f"{args.path}/{projects.PROJECT_FILE} exists already")
665
+ if not re.fullmatch(projects.NAME_PATTERN, name):
666
+ die(f"{name!r} is not a project name: use lowercase letters, digits and hyphens")
667
+ (path / "draft").mkdir(parents=True, exist_ok=True)
668
+ (path / projects.PROJECT_FILE).write_text(
669
+ NEW_PROJECT.format(name=name, purpose=args.purpose), encoding="utf-8")
670
+ if not (path / "draft" / "main.md").exists():
671
+ (path / "draft" / "main.md").write_text(NEW_DOC.format(name=name), encoding="utf-8")
672
+ print(f"wrote {args.path}/{projects.PROJECT_FILE} and a first doc, {args.path}/draft/main.md")
673
+ return 0
674
+
675
+
676
+ def launcher() -> str:
677
+ return f"""#!/usr/bin/env bash
678
+ # Written by `pubdoc init`. It names no release: it runs the pubdoc that
679
+ # {PIN}, beside it, pins. Change that line, or let pubrules's nightly
680
+ # move it, to move this repository to another release.
681
+ #
682
+ # Run this repository's pubdoc from its root, or from anywhere through this
683
+ # script's path:
684
+ #
685
+ # ./pubdoc check
686
+ # ./pubdoc build job-applications/veriff
687
+ #
688
+ # uvx fetches that release's wheel once and keeps it in uv's cache; nothing
689
+ # is installed into the repository or the system.
690
+ set -euo pipefail
691
+
692
+ pin="$(dirname "${{BASH_SOURCE[0]}}")/{PIN}"
693
+ if [ ! -f "$pin" ]; then
694
+ echo "pubdoc: no $pin, which pins the pubdoc ./pubdoc runs; run pubdoc init again" >&2
695
+ exit 1
696
+ fi
697
+ # The requirement is named by the distribution: pubdocrules, or pubdoc for a
698
+ # release from before the name changed.
699
+ url="$(sed -n 's/^[A-Za-z0-9_.-]* @ //p' "$pin" | head -n 1)"
700
+ if [ -z "$url" ]; then
701
+ echo "pubdoc: $pin has no line \"pubdocrules @ URL\"; run pubdoc init again" >&2
702
+ exit 1
703
+ fi
704
+
705
+ if ! command -v uvx >/dev/null 2>&1; then
706
+ echo "pubdoc: ./pubdoc runs pubdoc with uv, which is not installed: curl -LsSf https://astral.sh/uv/install.sh | sh" >&2
707
+ exit 127
708
+ fi
709
+
710
+ exec uvx --from "$url" pubdoc "$@"
711
+ """
712
+
713
+
714
+ def cmd_init(_: argparse.Namespace) -> int:
715
+ release = version()
716
+ path = Path(LAUNCHER)
717
+ if path.is_dir():
718
+ die(f"./{LAUNCHER} is a directory, such as an old pubdoc submodule; remove it first")
719
+ path.write_text(launcher(), encoding="utf-8")
720
+ path.chmod(0o755)
721
+ Path(PIN).write_text(f"{DISTRIBUTION} @ {WHEEL_URL.format(version=release)}\n", encoding="utf-8")
722
+ print(f"wrote ./{LAUNCHER}, which runs the pubdoc ./{PIN} pins: {release}")
723
+ return 0
724
+
725
+
726
+ def parser() -> argparse.ArgumentParser:
727
+ p = argparse.ArgumentParser(prog="pubdoc", description=__doc__.splitlines()[0])
728
+ p.add_argument("--version", action="version", version=f"pubdoc {version()}")
729
+ sub = p.add_subparsers(dest="command", required=True, metavar="COMMAND")
730
+
731
+ def add(name, func, help_text, *params):
732
+ cmd = sub.add_parser(name, help=help_text, description=help_text)
733
+ for param, kwargs in params:
734
+ cmd.add_argument(param, **kwargs)
735
+ cmd.set_defaults(func=func)
736
+
737
+ doc = ("name", {"help": "a doc's directory, <project>/<doc>"})
738
+ where = ("path", {"nargs": "?", "default": ".",
739
+ "help": "where to look: every project.yml git knows of below it, "
740
+ "or the project it is in (default: here)"})
741
+ variant = ("variant", {"nargs": "?", "help": "a variant; optional when only one is left"})
742
+ layout = ("layout", {"nargs": "?", "help": "a PDF layout; optional when only one is left"})
743
+ port = ("--port", {"help": "the port to serve on"})
744
+ add("check", cmd_check, "check every project.yml and doc.yml: the schema, and every "
745
+ "name they refer to", where)
746
+ add("list", cmd_list, "the projects and their docs", where)
747
+ add("variants", cmd_variants, "a doc's variants", doc)
748
+ add("open", cmd_open, "a live Curvenote site of a doc", doc, port)
749
+ add("build", cmd_build, "every variant x layout of a doc (or of each doc of a project) into "
750
+ "<doc>/build/<variant>/<layout>.<ext>; --all builds every doc here, reporting each that fails",
751
+ ("name", {"nargs": "?", "help": "a doc, <project>/<doc>, or a project"}),
752
+ ("--all", {"action": "store_true", "help": "every doc of every project in this repository"}),
753
+ ("--variant", {"help": "only this variant"}),
754
+ ("--layout", {"help": "only this layout"}),
755
+ ("--date", {"help": "the doc's date, YYYY-MM-DD, as approve gives it: printed by the template "
756
+ "unless a part sets its own, and the PDFs' creation time"}))
757
+ add("preview", cmd_preview, "review-builder's watch, build and Accept loop over one PDF render",
758
+ doc, variant, layout, port)
759
+ add("approve", cmd_approve, "build each variant of a doc, upload its renders to storage, sign a version "
760
+ "publet for it and record it in <doc>/versions/versions.yml", doc,
761
+ ("--variant", {"help": "only this variant"}),
762
+ ("--show", {"metavar": "LAYOUT", "help": "print this layout's address last, for review-builder"}),
763
+ ("--date", {"help": "the approval date, YYYY-MM-DD (default: today)"}),
764
+ ("--rebuilt-from", {"metavar": "COMMIT", "help": "the commit whose sources an earlier approved "
765
+ "version was built from, for one rebuilt to replace it"}),
766
+ ("--allow-dirty", {"action": "store_true", "help": "approve with uncommitted changes"}))
767
+ add("versions", cmd_versions, "a doc's versions, newest first", doc)
768
+ add("fetch", cmd_fetch, "download a version's renders, checked against its publet", doc,
769
+ ("version", {"nargs": "?", "type": int, "help": "a version number (default: the latest)"}),
770
+ ("--variant", {"help": "this variant's versions"}),
771
+ ("--layout", {"help": "only this layout"}),
772
+ ("--out", {"default": ".", "help": "the directory to save into (default: here)"}))
773
+ add("verify", cmd_verify, "check every versions.yml against its corpus's signed publets", where,
774
+ ("--remote", {"action": "store_true", "help": "and that every render in storage has its checksum"}))
775
+ add("corpus", cmd_corpus, "make the corpus versions are signed in, and its key, once (or rebuild its "
776
+ "store around a key restored with pubsec signing-key restore), and back the key up",
777
+ ("action", {"choices": ["init"], "help": "init: make what is missing"}),
778
+ ("project", {"nargs": "?", "help": "a project that names its own corpus (default: the repository's)"}),
779
+ ("--bitwarden-project", {"metavar": "ID", "help": "the Bitwarden project the key is backed up to, "
780
+ "when pubrules.json does not declare the key yet"}),
781
+ ("--backup-name", {"metavar": "NAME", "help": "the backup's name there, when not declared yet"}),
782
+ ("--no-backup", {"action": "store_true", "help": "do not run pubsec signing-key backup"}))
783
+ add("compare", cmd_compare, "whether two PDFs are the same document: pages, text, pixels",
784
+ ("first", {"help": "a PDF"}), ("second", {"help": "another PDF"}))
785
+ add("linkedin", cmd_linkedin, "a CV's plain-text export for LinkedIn",
786
+ ("index", {"help": "the CV's Markdown file"}))
787
+ add("init", cmd_init, f"write ./pubdoc and {PIN}, which pins this release for it to run with uvx")
788
+ add("new-project", cmd_new_project, "start a document project: a project.yml and a first doc",
789
+ ("path", {"help": "the project's directory; its name is the project's"}),
790
+ ("--purpose", {"default": "Say what this project is for", "help": "the project's purpose"}))
791
+ return p
792
+
793
+
794
+ def main(argv: list[str] | None = None) -> int:
795
+ args = parser().parse_args(argv)
796
+ return args.func(args)
797
+
798
+
799
+ if __name__ == "__main__": # pragma: no cover
800
+ sys.exit(main())