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.
- pubdoc/__init__.py +1 -0
- pubdoc/__main__.py +5 -0
- pubdoc/cli.py +800 -0
- pubdoc/compare.py +121 -0
- pubdoc/corpus.py +245 -0
- pubdoc/fonts/DejaVuSans-Bold.ttf +0 -0
- pubdoc/fonts/DejaVuSans.ttf +0 -0
- pubdoc/fonts/LICENCE-Ubuntu.txt +96 -0
- pubdoc/fonts/LICENSE-DejaVu.txt +78 -0
- pubdoc/fonts/LICENSE-Liberation.txt +130 -0
- pubdoc/fonts/LiberationSans-Bold.ttf +0 -0
- pubdoc/fonts/LiberationSans-BoldItalic.ttf +0 -0
- pubdoc/fonts/LiberationSans-Italic.ttf +0 -0
- pubdoc/fonts/LiberationSans-Regular.ttf +0 -0
- pubdoc/fonts/README.md +21 -0
- pubdoc/fonts/Ubuntu-R.ttf +0 -0
- pubdoc/projects.py +501 -0
- pubdoc/registry.py +54 -0
- pubdoc/schema/doc.schema.json +14 -0
- pubdoc/schema/project.schema.json +142 -0
- pubdoc/schema/pubdoc.schema.json +16 -0
- pubdoc/settings.py +66 -0
- pubdoc/storage.py +126 -0
- pubdoc/templates/annotations.mjs +116 -0
- pubdoc/templates/charged-ieee/template.typ +41 -0
- pubdoc/templates/charged-ieee/template.yml +28 -0
- pubdoc/templates/cv-sidebar/cv-sidebar.typ +113 -0
- pubdoc/templates/cv-sidebar/template.typ +11 -0
- pubdoc/templates/cv-sidebar/template.yml +23 -0
- pubdoc/templates/lapreprint-typst/LICENSE +21 -0
- pubdoc/templates/lapreprint-typst/frontmatter.typ +244 -0
- pubdoc/templates/lapreprint-typst/lapreprint.typ +314 -0
- pubdoc/templates/lapreprint-typst/template.typ +112 -0
- pubdoc/templates/lapreprint-typst/template.yml +82 -0
- pubdoc/templates/linkedin-text.mjs +127 -0
- pubdoc/templates/pub-plugin.mjs +117 -0
- pubdoc/versions.py +383 -0
- pubdocrules-0.5.0.dist-info/METADATA +355 -0
- pubdocrules-0.5.0.dist-info/RECORD +43 -0
- pubdocrules-0.5.0.dist-info/WHEEL +5 -0
- pubdocrules-0.5.0.dist-info/entry_points.txt +2 -0
- pubdocrules-0.5.0.dist-info/licenses/LICENSE +202 -0
- 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())
|