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
|
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
|
+
}
|