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
Binary file
Binary file
pubdoc/fonts/README.md ADDED
@@ -0,0 +1,21 @@
1
+ # The fonts pubdoc renders with
2
+
3
+ pubdoc runs typst with `--ignore-system-fonts` and this directory as its only
4
+ font path, so a render depends on the pubdoc release, not on the fonts a
5
+ machine happens to have: on 2026-11-19 a laptop's newly installed FreeSans
6
+ took over the verdict symbols (✓ ✗ ◪) from DejaVu Sans and reflowed every
7
+ line of a fact-check. Beside these, typst carries Libertinus Serif, New
8
+ Computer Modern (and its Math) and DejaVu Sans Mono itself.
9
+
10
+ These are the system fonts the PDFs approved before then embed, taken from
11
+ Ubuntu's packages:
12
+
13
+ | File | Font | Package | Licence |
14
+ |---|---|---|---|
15
+ | DejaVuSans.ttf, DejaVuSans-Bold.ttf | DejaVu Sans 2.37 | fonts-dejavu-core 2.37-8build1 | Bitstream Vera / DejaVu (public domain changes), LICENSE-DejaVu.txt |
16
+ | Ubuntu-R.ttf | Ubuntu Regular 0.869 | fonts-ubuntu 0.869+git20240321-0ubuntu2 | Ubuntu Font Licence 1.0, LICENCE-Ubuntu.txt |
17
+ | LiberationSans-*.ttf | Liberation Sans 2.1.5 | fonts-liberation 1:2.1.5-3build1 | SIL Open Font License 1.1, LICENSE-Liberation.txt |
18
+
19
+ pubdoc's own LICENSE is Apache-2.0, but these font files are not: each is under the licence shipped beside it (Bitstream Vera/DejaVu, Ubuntu Font Licence 1.0, SIL OFL 1.1). Each licence allows redistributing the fonts unmodified with software. A
20
+ template that wants another font names one here, added with its licence, or
21
+ falls back to these.
Binary file
pubdoc/projects.py ADDED
@@ -0,0 +1,501 @@
1
+ """Document projects: finding them in a repository, loading and checking
2
+ their project.yml and doc.yml, and resolving which file holds each part.
3
+
4
+ A project is a directory holding a project.yml. Its docs are the
5
+ directories beside that file holding a doc.yml or a file for one of its
6
+ parts:
7
+
8
+ <project>/project.yml
9
+ <project>/shared/<name>/<part>.md a shared part docs start from
10
+ <project>/<doc>/<part>.md a doc's part, MyST Markdown
11
+ <project>/<doc>/<part>.<variant>.md replaces <part>.md for that variant
12
+ <project>/<doc>/doc.yml optional, only narrows project.yml
13
+ <project>/<doc>/refs.bib optional bibliography
14
+ """
15
+
16
+ from __future__ import annotations
17
+
18
+ import json
19
+ import os
20
+ import subprocess
21
+ from dataclasses import dataclass, field
22
+ from functools import cache
23
+ from importlib import resources
24
+ from pathlib import Path
25
+
26
+ import yaml
27
+ from jsonschema import Draft202012Validator
28
+ from referencing import Registry, Resource
29
+
30
+ from . import registry
31
+
32
+ PROJECT_FILE = "project.yml"
33
+ DOC_FILE = "doc.yml"
34
+ SHARED = "shared"
35
+ BUILD = "build"
36
+ VERSIONS = "versions"
37
+ # Directories inside a project that are never docs.
38
+ NOT_DOCS = {SHARED, BUILD, VERSIONS, "node_modules"}
39
+ # Directories a search without git never enters.
40
+ SKIPPED = {BUILD, "node_modules", ".git", ".venv", "_build"}
41
+ NAME_PATTERN = "^[a-z0-9][a-z0-9-]*$"
42
+ TEMPLATE_PATTERN = "^(?:[a-z0-9][a-z0-9-]*|[^/].*/.*)$"
43
+ READERS = ("named", "signed-in", "public") # narrowest first
44
+
45
+
46
+ @dataclass(frozen=True)
47
+ class Problem:
48
+ path: Path
49
+ message: str
50
+
51
+ def __str__(self) -> str:
52
+ return f"{shown(self.path)}: {self.message}"
53
+
54
+
55
+ def shown(path: Path) -> str:
56
+ """A path as the user would type it: relative to here when it is below here."""
57
+ try:
58
+ return str(path.resolve().relative_to(Path.cwd().resolve())) or "."
59
+ except ValueError:
60
+ return str(path)
61
+
62
+
63
+ @dataclass
64
+ class Doc:
65
+ project: "Project"
66
+ path: Path
67
+ config: dict = field(default_factory=dict)
68
+
69
+ @property
70
+ def name(self) -> str:
71
+ return self.path.name
72
+
73
+ @property
74
+ def label(self) -> str:
75
+ return shown(self.path)
76
+
77
+ def variants(self) -> list[str]:
78
+ everything = list(self.project.config["variants"])
79
+ chosen = self.config.get("variants")
80
+ return [v for v in everything if v in chosen] if chosen else everything
81
+
82
+ def layouts(self) -> list[str]:
83
+ everything = list(self.project.config["layouts"])
84
+ chosen = self.config.get("layouts")
85
+ return [layout for layout in everything if layout in chosen] if chosen else everything
86
+
87
+ def review(self) -> list[dict]:
88
+ return self.config.get("review", self.project.config.get("review", []))
89
+
90
+ def publish(self) -> list[dict]:
91
+ return self.config.get("publish", self.project.config.get("publish", []))
92
+
93
+ def source(self, part: str, variant: str) -> Path | None:
94
+ """The file that holds `part` for `variant`: the doc's own override,
95
+ its own part, then the shared part's override and the shared part."""
96
+ places = [self.path]
97
+ if shared := self.project.shared_dir(part):
98
+ places.append(shared)
99
+ for place in places:
100
+ for candidate in (place / f"{part}.{variant}.md", place / f"{part}.md"):
101
+ if candidate.is_file():
102
+ return candidate
103
+ return None
104
+
105
+ def renders(self, variant: str | None = None, layout: str | None = None) -> list["Render"]:
106
+ """Every variant x layout this doc builds, or just those named; a
107
+ layout whose (optional) part the doc does not supply is left out."""
108
+ found = []
109
+ for v in self.variants():
110
+ if variant and v != variant:
111
+ continue
112
+ for name in self.layouts():
113
+ if layout and name != layout:
114
+ continue
115
+ spec = self.project.config["layouts"][name]
116
+ source = self.source(spec["part"], v)
117
+ if source:
118
+ found.append(Render(self, v, name, spec, source))
119
+ return found
120
+
121
+
122
+ @dataclass(frozen=True)
123
+ class Render:
124
+ doc: Doc
125
+ variant: str
126
+ layout: str
127
+ spec: dict
128
+ source: Path
129
+
130
+ @property
131
+ def extension(self) -> str:
132
+ return {"pdf": "pdf", "text": "txt", "html": "html"}[self.spec["format"]]
133
+
134
+ @property
135
+ def output(self) -> Path:
136
+ return self.doc.path / BUILD / self.variant / f"{self.layout}.{self.extension}"
137
+
138
+ @property
139
+ def typst_source(self) -> Path:
140
+ """Where Curvenote writes a template layout's Typst, in a directory of
141
+ its own: a template's support files land beside it, and a layout named
142
+ like one of them (lapreprint, beside lapreprint.typ) would otherwise
143
+ overwrite it, or import itself."""
144
+ return self.doc.path / BUILD / self.variant / self.layout / "main.typ"
145
+
146
+
147
+ @dataclass
148
+ class Project:
149
+ path: Path
150
+ config: dict
151
+ docs: list[Doc] = field(default_factory=list)
152
+
153
+ @property
154
+ def file(self) -> Path:
155
+ return self.path / PROJECT_FILE
156
+
157
+ @property
158
+ def name(self) -> str:
159
+ return self.config.get("project", self.path.name)
160
+
161
+ def template_dir(self, template: str) -> Path | None:
162
+ """A local template's directory, or None for a template pubdoc carries."""
163
+ return (self.path / template).resolve() if is_path(template) else None
164
+
165
+ def shared_dir(self, part: str) -> Path | None:
166
+ spec = self.config.get("parts", {}).get(part, {})
167
+ return self.path / spec["starts-from"] if "starts-from" in spec else None
168
+
169
+
170
+ def is_path(template: str) -> bool:
171
+ """A layout's template is a path in the repository when it holds a /,
172
+ and the name of a template pubdoc carries when it does not."""
173
+ return "/" in template
174
+
175
+
176
+ # Finding projects --------------------------------------------------------
177
+
178
+ def git_root(start: Path) -> Path | None:
179
+ """The git work tree holding `start`, if it is in one."""
180
+ done = subprocess.run(["git", "-C", str(start), "rev-parse", "--show-toplevel"],
181
+ capture_output=True, text=True)
182
+ return Path(done.stdout.strip()).resolve() if done.returncode == 0 else None
183
+
184
+
185
+ def repo_root(start: Path) -> Path:
186
+ """The git work tree holding `start`, else `start` itself."""
187
+ return git_root(start) or start
188
+
189
+
190
+ def project_files(start: Path) -> list[Path]:
191
+ """Every project.yml at or below `start`: the ones git tracks or would
192
+ (git ls-files, so ignored build output never counts), or, outside a
193
+ git work tree, every one on disk outside build output."""
194
+ start = start.resolve()
195
+ done = subprocess.run(["git", "-C", str(start), "ls-files", "-z", "--cached", "--others",
196
+ "--exclude-standard", "--", "."], capture_output=True, text=True)
197
+ if done.returncode == 0:
198
+ found = {start / line for line in done.stdout.split("\0")
199
+ if line == PROJECT_FILE or line.endswith("/" + PROJECT_FILE)}
200
+ return sorted(path for path in found if path.is_file())
201
+ found = []
202
+ for here, dirs, files in os.walk(start):
203
+ dirs[:] = sorted(d for d in dirs if d not in SKIPPED and not d.startswith("."))
204
+ if PROJECT_FILE in files:
205
+ found.append(Path(here) / PROJECT_FILE)
206
+ return sorted(found)
207
+
208
+
209
+ def enclosing_project(path: Path) -> Path | None:
210
+ """The project.yml in `path` or the nearest directory above it."""
211
+ for here in [path.resolve(), *path.resolve().parents]:
212
+ if (here / PROJECT_FILE).is_file():
213
+ return here / PROJECT_FILE
214
+ return None
215
+
216
+
217
+ def find(start: Path) -> list[Path]:
218
+ """The project files a command given `start` acts on: every one below
219
+ it, else the one it is inside."""
220
+ found = project_files(start)
221
+ if not found and (inside := enclosing_project(start)):
222
+ found = [inside]
223
+ return found
224
+
225
+
226
+ # Loading -----------------------------------------------------------------
227
+
228
+ def read_yaml(path: Path, problems: list[Problem]) -> dict | None:
229
+ try:
230
+ data = yaml.safe_load(path.read_text(encoding="utf-8"))
231
+ except yaml.YAMLError as e:
232
+ problems.append(Problem(path, f"is not valid YAML: {e}"))
233
+ return None
234
+ if data is None:
235
+ data = {}
236
+ if not isinstance(data, dict):
237
+ problems.append(Problem(path, "must be a YAML mapping"))
238
+ return None
239
+ return data
240
+
241
+
242
+ @cache
243
+ def validators() -> dict[str, Draft202012Validator]:
244
+ schemas = {name: json.loads((resources.files("pubdoc") / "schema" / f"{name}.schema.json")
245
+ .read_text(encoding="utf-8"))
246
+ for name in ("project", "doc", "pubdoc")}
247
+ store = Registry().with_resources(
248
+ (schema["$id"], Resource.from_contents(schema)) for schema in schemas.values())
249
+ return {name: Draft202012Validator(schema, registry=store) for name, schema in schemas.items()}
250
+
251
+
252
+ def schema_problems(kind: str, data: dict, path: Path) -> list[Problem]:
253
+ errors = sorted(validators()[kind].iter_errors(data), key=lambda e: list(map(str, e.absolute_path)))
254
+ return [Problem(path, describe(e)) for e in errors]
255
+
256
+
257
+ def describe(error) -> str:
258
+ where = ".".join(str(p) for p in error.absolute_path)
259
+ if error.validator == "oneOf":
260
+ message = "needs a template or an exporter, and not both"
261
+ elif error.validator == "anyOf":
262
+ message = "needs automatic checkers, a human sign-off, or both"
263
+ elif error.validator == "pattern" and error.validator_value == NAME_PATTERN:
264
+ message = f"{error.instance!r} is not a name: use lowercase letters, digits and hyphens"
265
+ elif error.validator == "pattern" and error.validator_value == TEMPLATE_PATTERN:
266
+ message = (f"{error.instance!r} is neither a template name nor a path relative to the "
267
+ "project (a path holds a /, and does not start with one)")
268
+ elif error.validator == "pattern" and str(error.validator_value).startswith("^shared/"):
269
+ message = f"{error.instance!r} is not shared/<name>"
270
+ elif error.validator == "propertyNames":
271
+ message = f"{error.instance!r} is not a name: use lowercase letters, digits and hyphens"
272
+ else:
273
+ message = error.message
274
+ return f"{where}: {message}" if where else message
275
+
276
+
277
+ def load(file: Path, problems: list[Problem]) -> Project | None:
278
+ """The project in `file`, with its docs, or None when project.yml is
279
+ unreadable or breaks the schema (those problems are added)."""
280
+ data = read_yaml(file, problems)
281
+ if data is None:
282
+ return None
283
+ found = schema_problems("project", data, file)
284
+ if found:
285
+ problems.extend(found)
286
+ return None
287
+ project = Project(file.parent.resolve(), data)
288
+ parts = set(data["parts"])
289
+ for child in sorted(project.path.iterdir()):
290
+ if (not child.is_dir() or child.name in NOT_DOCS or child.name[0] in "._"
291
+ or (child / PROJECT_FILE).exists()):
292
+ continue
293
+ if not ((child / DOC_FILE).is_file() or any(
294
+ f.name.split(".")[0] in parts for f in child.glob("*.md"))):
295
+ continue
296
+ config = {}
297
+ if (child / DOC_FILE).is_file():
298
+ config = read_yaml(child / DOC_FILE, problems)
299
+ if config is not None:
300
+ if found := schema_problems("doc", config, child / DOC_FILE):
301
+ problems.extend(found)
302
+ config = None
303
+ config = config or {}
304
+ project.docs.append(Doc(project, child.resolve(), config))
305
+ return project
306
+
307
+
308
+ # Checking ----------------------------------------------------------------
309
+
310
+ def missing(kind: str, name: str, known) -> str:
311
+ return f"no {kind} {name!r} ({', '.join(sorted(known)) or 'none'})"
312
+
313
+
314
+ def check(project: Project) -> tuple[list[Problem], list[str]]:
315
+ """Every cross-reference in a loaded project and its docs: problems,
316
+ and notes about names pubdoc knows but does not implement yet."""
317
+ problems: list[Problem] = []
318
+ notes: set[str] = set()
319
+ file, config = project.file, project.config
320
+ parts, variants, layouts = config["parts"], config["variants"], config["layouts"]
321
+
322
+ for part, spec in parts.items():
323
+ if "starts-from" in spec:
324
+ shared = project.path / spec["starts-from"]
325
+ if not (shared / f"{part}.md").is_file():
326
+ problems.append(Problem(file, f"parts.{part}.starts-from: no {spec['starts-from']}/{part}.md"))
327
+ else:
328
+ problems.extend(overrides(shared, {part}, variants))
329
+
330
+ templates = registry.templates()
331
+ for name, spec in layouts.items():
332
+ where = f"layouts.{name}"
333
+ if spec["part"] not in parts:
334
+ problems.append(Problem(file, f"{where}.part: {missing('part', spec['part'], parts)}"))
335
+ if "template" in spec and is_path(spec["template"]):
336
+ if found := local_template_problem(project, spec["template"]):
337
+ problems.append(Problem(file, f"{where}.template: {found}"))
338
+ elif spec["format"] not in registry.TEMPLATE_FORMATS:
339
+ problems.append(Problem(file, f"{where}.format: {spec['template']} makes "
340
+ f"{', '.join(registry.TEMPLATE_FORMATS)}, not {spec['format']}"))
341
+ elif "template" in spec and spec["template"] not in templates:
342
+ problems.append(Problem(file, f"{where}.template: {missing('template', spec['template'], templates)}"))
343
+ elif "exporter" in spec and spec["exporter"] not in registry.EXPORTERS:
344
+ problems.append(Problem(file, f"{where}.exporter: "
345
+ f"{missing('exporter', spec['exporter'], registry.EXPORTERS)}"))
346
+ elif spec["format"] not in registry.formats(spec):
347
+ maker = spec.get("template") or spec.get("exporter")
348
+ problems.append(Problem(file, f"{where}.format: {maker} makes "
349
+ f"{', '.join(registry.formats(spec))}, not {spec['format']}"))
350
+
351
+ reviewers = config.get("roles", {}).get("reviewers", [])
352
+ problems.extend(review_problems(file, "review", config.get("review", []), reviewers, notes))
353
+ for i, entry in enumerate(config.get("publish", [])):
354
+ problems.extend(publication_problems(file, f"publish[{i}]", entry, layouts, variants, notes))
355
+
356
+ for doc in project.docs:
357
+ problems.extend(doc_problems(doc, notes))
358
+ return problems, sorted(notes)
359
+
360
+
361
+ def local_template_problem(project: Project, template: str) -> str | None:
362
+ """Why a local template directory cannot be built with, if it cannot:
363
+ it must be inside the repository (outside a git work tree, anywhere), hold a template.yml (without one,
364
+ Curvenote takes the path for the name of a template to download) and
365
+ be a Typst template, the kind pubdoc builds."""
366
+ path = project.template_dir(template)
367
+ root = git_root(project.path)
368
+ if root and not path.is_relative_to(root):
369
+ return f"{template} is outside the repository ({shown(root)})"
370
+ if not path.is_dir():
371
+ return f"no directory {shown(path)}"
372
+ spec = path / "template.yml"
373
+ if not spec.is_file():
374
+ return (f"{shown(path)} has no template.yml, which Curvenote needs "
375
+ "to take a directory as a template")
376
+ try:
377
+ kind = (yaml.safe_load(spec.read_text(encoding="utf-8")) or {}).get("kind")
378
+ except (yaml.YAMLError, AttributeError):
379
+ return f"{shown(spec)} is not a YAML mapping"
380
+ if kind != "typst":
381
+ return f"{shown(spec)} is a {kind or 'kindless'} template; pubdoc builds Typst templates (kind: typst)"
382
+ return None
383
+
384
+
385
+ def overrides(where: Path, parts, variants) -> list[Problem]:
386
+ """A <part>.<x>.md whose x is no variant: most likely a typo."""
387
+ found = []
388
+ for f in sorted(where.glob("*.*.md")):
389
+ part, variant = f.name.split(".")[:2]
390
+ if part in parts and variant not in variants:
391
+ found.append(Problem(f, missing("variant", variant, variants)))
392
+ return found
393
+
394
+
395
+ def review_problems(file: Path, where: str, steps: list[dict], reviewers, notes: set[str]) -> list[Problem]:
396
+ found, seen = [], set()
397
+ for i, step in enumerate(steps):
398
+ here = f"{where}[{i}]"
399
+ if step["step"] in seen:
400
+ found.append(Problem(file, f"{here}.step: {step['step']!r} is named twice"))
401
+ seen.add(step["step"])
402
+ for checker in step.get("automatic", []):
403
+ if checker not in registry.CHECKERS:
404
+ found.append(Problem(file, f"{here}.automatic: {missing('checker', checker, registry.CHECKERS)}"))
405
+ elif not registry.CHECKERS[checker].implemented:
406
+ notes.add(f"checker {checker!r} is not implemented yet: a later pubdoc runs it")
407
+ wanted = step.get("human", {}).get("reviewers", 0)
408
+ if wanted > len(reviewers):
409
+ found.append(Problem(file, f"{here}.human: needs {wanted} reviewers, "
410
+ f"and roles.reviewers names {len(reviewers)}"))
411
+ return found
412
+
413
+
414
+ def publication_problems(file: Path, where: str, entry: dict, layouts, variants,
415
+ notes: set[str]) -> list[Problem]:
416
+ found = []
417
+ if entry["place"] not in registry.PLACES:
418
+ found.append(Problem(file, f"{where}.place: {missing('place', entry['place'], registry.PLACES)}"))
419
+ elif not registry.PLACES[entry["place"]].implemented:
420
+ notes.add(f"place {entry['place']!r} is not implemented yet: a later pubdoc publishes there")
421
+ for layout in entry["layouts"]:
422
+ if layout not in layouts:
423
+ found.append(Problem(file, f"{where}.layouts: {missing('layout', layout, layouts)}"))
424
+ for variant in entry.get("variants", []):
425
+ if variant not in variants:
426
+ found.append(Problem(file, f"{where}.variants: {missing('variant', variant, variants)}"))
427
+ return found
428
+
429
+
430
+ def doc_problems(doc: Doc, notes: set[str]) -> list[Problem]:
431
+ config = doc.project.config
432
+ found = overrides(doc.path, config["parts"], config["variants"])
433
+ file = doc.path / DOC_FILE
434
+ for key, everything in (("variants", config["variants"]), ("layouts", config["layouts"])):
435
+ for name in doc.config.get(key, []):
436
+ if name not in everything:
437
+ found.append(Problem(file, f"{key}: {missing(key[:-1], name, everything)} in project.yml"))
438
+ if "review" in doc.config:
439
+ reviewers = config.get("roles", {}).get("reviewers", [])
440
+ found.extend(review_problems(file, "review", doc.config["review"], reviewers, notes))
441
+ found.extend(narrower_review(file, config.get("review", []), doc.config["review"]))
442
+ if "publish" in doc.config:
443
+ for i, entry in enumerate(doc.config["publish"]):
444
+ here = f"publish[{i}]"
445
+ found.extend(publication_problems(file, here, entry, doc.layouts(), doc.variants(), notes))
446
+ found.extend(narrower_publication(file, here, entry, config.get("publish", []), config["variants"]))
447
+
448
+ for part, spec in config["parts"].items():
449
+ if not spec["required"]:
450
+ continue
451
+ for variant in doc.variants():
452
+ if not doc.source(part, variant):
453
+ start = f", and shared part {spec['starts-from']} has none" if "starts-from" in spec else ""
454
+ found.append(Problem(doc.path, f"no {part}.md or {part}.{variant}.md for required part "
455
+ f"{part!r} in variant {variant!r}{start}"))
456
+ return found
457
+
458
+
459
+ def narrower_review(file: Path, project_steps: list[dict], doc_steps: list[dict]) -> list[Problem]:
460
+ """A doc keeps every project review step, in order, and may only add
461
+ checkers, reviewers or steps of its own."""
462
+ found = []
463
+ names = [step["step"] for step in doc_steps]
464
+ position = -1
465
+ for step in project_steps:
466
+ name = step["step"]
467
+ if name not in names:
468
+ found.append(Problem(file, f"review: drops the project's review step {name!r}"))
469
+ continue
470
+ if names.index(name) < position:
471
+ found.append(Problem(file, f"review: moves the project's review step {name!r} before an earlier one"))
472
+ position = max(position, names.index(name))
473
+ mine = doc_steps[names.index(name)]
474
+ if dropped := set(step.get("automatic", [])) - set(mine.get("automatic", [])):
475
+ found.append(Problem(file, f"review: step {name!r} drops checkers {', '.join(sorted(dropped))}"))
476
+ wanted = step.get("human", {}).get("reviewers", 0)
477
+ if mine.get("human", {}).get("reviewers", 0) < wanted:
478
+ found.append(Problem(file, f"review: step {name!r} needs {wanted} human reviewers in project.yml"))
479
+ return found
480
+
481
+
482
+ def narrower_publication(file: Path, where: str, entry: dict, project_entries: list[dict],
483
+ all_variants) -> list[Problem]:
484
+ """A doc publishes only what a project publication to the same place
485
+ already allows, to no wider readers."""
486
+ candidates = [p for p in project_entries if p["place"] == entry["place"]]
487
+ if not candidates:
488
+ return [Problem(file, f"{where}.place: project.yml does not publish to {entry['place']!r}")]
489
+ reasons = []
490
+ for p in candidates:
491
+ why = []
492
+ if extra := set(entry["layouts"]) - set(p["layouts"]):
493
+ why.append(f"layouts {', '.join(sorted(extra))}")
494
+ if extra := set(entry.get("variants", all_variants)) - set(p.get("variants", all_variants)):
495
+ why.append(f"variants {', '.join(sorted(extra))}")
496
+ if READERS.index(entry["readers"]) > READERS.index(p["readers"]):
497
+ why.append(f"{entry['readers']} readers (project.yml: {p['readers']})")
498
+ if not why:
499
+ return []
500
+ reasons.append(" and ".join(why))
501
+ return [Problem(file, f"{where}: widens what project.yml publishes to {entry['place']!r}: {reasons[0]}")]
pubdoc/registry.py ADDED
@@ -0,0 +1,54 @@
1
+ """The names a project.yml may use: pubdoc's templates, exporters,
2
+ checkers and places.
3
+
4
+ A project only picks and configures these; what each one does lives in
5
+ pubdoc. Checkers and places are declared before they are implemented, so a
6
+ project can name the review steps and places it will use: `pubdoc check`
7
+ says which are not implemented yet, and does not fail for them.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ from dataclasses import dataclass
13
+ from importlib import resources
14
+
15
+
16
+ @dataclass(frozen=True)
17
+ class Plugin:
18
+ summary: str
19
+ implemented: bool = False
20
+
21
+
22
+ # Exporters render a part without a template: name -> the formats it makes.
23
+ EXPORTERS: dict[str, tuple[str, ...]] = {
24
+ "linkedin": ("text",),
25
+ }
26
+
27
+ # Every template pubdoc carries is a Typst template: it makes a PDF.
28
+ TEMPLATE_FORMATS = ("pdf",)
29
+
30
+ CHECKERS: dict[str, Plugin] = {
31
+ "build": Plugin("every variant and layout of the doc builds"),
32
+ "links": Plugin("every link resolves"),
33
+ "spelling": Plugin("no unknown words"),
34
+ "private-info": Plugin("no private information in a public render"),
35
+ }
36
+
37
+ PLACES: dict[str, Plugin] = {
38
+ "storage": Plugin("storage.sustenaut.eu, with a link in the doc's versions"),
39
+ "pub": Plugin("pub.sustenaut.eu"),
40
+ }
41
+
42
+
43
+ def templates() -> list[str]:
44
+ """The templates this release carries: each a directory with a template.yml."""
45
+ root = resources.files("pubdoc") / "templates"
46
+ return sorted(child.name for child in root.iterdir()
47
+ if child.is_dir() and (child / "template.yml").is_file())
48
+
49
+
50
+ def formats(layout: dict) -> tuple[str, ...]:
51
+ """The formats a layout's template or exporter can make."""
52
+ if "template" in layout:
53
+ return TEMPLATE_FORMATS
54
+ return EXPORTERS.get(layout.get("exporter", ""), ())
@@ -0,0 +1,14 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://github.com/Sustenaut/pubdoc/blob/main/src/pubdoc/schema/doc.schema.json",
4
+ "title": "pubdoc doc.yml",
5
+ "description": "An optional doc.yml beside a doc's parts. It can only narrow its project.yml: fewer variants, layouts or publications, narrower readers, and review steps that keep every project step and may only add checkers, reviewers or steps.",
6
+ "type": "object",
7
+ "additionalProperties": false,
8
+ "properties": {
9
+ "variants": {"$ref": "project.schema.json#/$defs/names", "description": "The project variants this doc has."},
10
+ "layouts": {"$ref": "project.schema.json#/$defs/names", "description": "The project layouts this doc is rendered in."},
11
+ "review": {"$ref": "project.schema.json#/$defs/review"},
12
+ "publish": {"type": "array", "items": {"$ref": "project.schema.json#/$defs/publication"}}
13
+ }
14
+ }