basstler-hub 4.2.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.
- basstler/plan_site/__init__.py +0 -0
- basstler/plan_site/__main__.py +532 -0
- basstler/plan_site/attach_approval.py +207 -0
- basstler/plan_site/build_start.py +289 -0
- basstler/plan_site/cards.py +498 -0
- basstler/plan_site/chip_tone.py +102 -0
- basstler/plan_site/dispatch_check.py +569 -0
- basstler/plan_site/entry_point_approval.py +176 -0
- basstler/plan_site/exceptions.py +259 -0
- basstler/plan_site/handover_button.py +37 -0
- basstler/plan_site/hub.py +467 -0
- basstler/plan_site/hub_page.py +725 -0
- basstler/plan_site/item_classifier.py +300 -0
- basstler/plan_site/live_state_display.py +104 -0
- basstler/plan_site/merge_workflow_refresh.py +68 -0
- basstler/plan_site/plan_overview.py +128 -0
- basstler/plan_site/plan_page.py +190 -0
- basstler/plan_site/plan_page_header.py +54 -0
- basstler/plan_site/plan_page_vocabulary.py +84 -0
- basstler/plan_site/publication.py +796 -0
- basstler/plan_site/site_read.py +149 -0
- basstler/plan_site/site_repository.py +125 -0
- basstler/plan_site/site_vocabulary.py +55 -0
- basstler/plan_site/token_storage.py +256 -0
- basstler/plan_site/user_steps.py +477 -0
- basstler/plan_site/workflows.py +514 -0
- basstler/templates/hub.html +25 -0
- basstler/templates/plan_handover_guide.md.jinja +108 -0
- basstler/templates/plan_handover_pull_request.md.jinja +42 -0
- basstler/templates/plan_handover_summary.md.jinja +6 -0
- basstler/templates/plan_handover_taken_over.md.jinja +12 -0
- basstler/templates/plan_site_dispatch_workflow.yml +36 -0
- basstler/templates/plan_site_merge_workflow.yml +14 -0
- basstler/templates/plan_site_store_token_command.sh +6 -0
- basstler/templates/plan_site_workflow.yml +24 -0
- basstler/templates/review_triage_mark_viewed_caller.yml +34 -0
- basstler/templates/review_triage_mark_viewed_setup.md.jinja +42 -0
- basstler/templates/shared_token_store_command.sh +10 -0
- basstler/templates/site.css +267 -0
- basstler/templates/site_index.html +26 -0
- basstler/templates/site_layout.html +18 -0
- basstler/templates/site_live_progress.js +119 -0
- basstler/templates/site_live_state.js +28 -0
- basstler/templates/site_parts.html +97 -0
- basstler/templates/site_plan.html +169 -0
- basstler/templates/site_plan.js +171 -0
- basstler/templates/site_plan_pull_request_recheck.js +195 -0
- basstler_hub-4.2.0.dist-info/METADATA +21 -0
- basstler_hub-4.2.0.dist-info/RECORD +53 -0
- basstler_hub-4.2.0.dist-info/WHEEL +4 -0
- basstler_hub-4.2.0.dist-info/entry_points.txt +2 -0
- basstler_hub-4.2.0.dist-info/licenses/LICENSE +202 -0
- basstler_hub-4.2.0.dist-info/licenses/NOTICE +13 -0
|
File without changes
|
|
@@ -0,0 +1,532 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""
|
|
3
|
+
Build the plan site: the hub, each repository's plans, and each plan's page.
|
|
4
|
+
|
|
5
|
+
Reads the hub file, fetches every repository it lists, and renders that repository's
|
|
6
|
+
plans with the live state of every pull request they reference. Nothing here needs a
|
|
7
|
+
Claude session or belongs to an account, so the site is the same for everyone:
|
|
8
|
+
|
|
9
|
+
<site>/ the hub, one card per repository
|
|
10
|
+
<site>/<owner>/<repo>/ that repository's plans
|
|
11
|
+
<site>/<owner>/<repo>/<plan>/ a plan's page
|
|
12
|
+
|
|
13
|
+
Usage:
|
|
14
|
+
python3 -m basstler.plan_site --registry <owner/repo> --output _site \\
|
|
15
|
+
[--site-url <url>] [--remote-root <url or directory>]
|
|
16
|
+
|
|
17
|
+
The hub file is read off the registry's notes branch. A plan whose manifest fails
|
|
18
|
+
validation, or a repository whose notes cannot be fetched, is reported and left out;
|
|
19
|
+
everything else is still published.
|
|
20
|
+
"""
|
|
21
|
+
|
|
22
|
+
from __future__ import annotations
|
|
23
|
+
|
|
24
|
+
import argparse
|
|
25
|
+
import hashlib
|
|
26
|
+
import re
|
|
27
|
+
import sys
|
|
28
|
+
import tempfile
|
|
29
|
+
from abc import ABC, abstractmethod
|
|
30
|
+
from dataclasses import dataclass, field
|
|
31
|
+
from datetime import UTC, datetime
|
|
32
|
+
from enum import StrEnum
|
|
33
|
+
from pathlib import Path
|
|
34
|
+
from typing import Any
|
|
35
|
+
|
|
36
|
+
import yaml
|
|
37
|
+
|
|
38
|
+
from basstler.github.pull_request_source import (
|
|
39
|
+
GitHubPullRequestSource,
|
|
40
|
+
PullRequestSource,
|
|
41
|
+
)
|
|
42
|
+
from basstler.github.repository import GitHubAddress, Repository
|
|
43
|
+
from basstler.locations import ProjectLocation
|
|
44
|
+
from basstler.plan.dependencies import DependencyResolver, PlanDirectory
|
|
45
|
+
from basstler.plan.exceptions import PlanValidationError
|
|
46
|
+
from basstler.plan.model import PlanDocument
|
|
47
|
+
from basstler.plan.repository_rules import RepositoryRules
|
|
48
|
+
from basstler.plan.structure import Plan
|
|
49
|
+
from basstler.plan.validation import PlanValidator
|
|
50
|
+
from basstler.plan_site.cards import PlanTimeAttribute
|
|
51
|
+
from basstler.plan_site.hub import NotesBranch, PlanHub, SiteAddress
|
|
52
|
+
from basstler.plan_site.hub_page import (
|
|
53
|
+
CountedItem,
|
|
54
|
+
HubPage,
|
|
55
|
+
PlanSummary,
|
|
56
|
+
ProgressCard,
|
|
57
|
+
RepositoryIndexPage,
|
|
58
|
+
RepositorySummary,
|
|
59
|
+
SiteStylesheet,
|
|
60
|
+
SiteSummary,
|
|
61
|
+
SkippedPage,
|
|
62
|
+
)
|
|
63
|
+
from basstler.plan_site.item_classifier import ItemClassifier
|
|
64
|
+
from basstler.plan_site.plan_page import PlanPage, RenderedPlanPage
|
|
65
|
+
from basstler.plan_site.plan_page_header import PlanPageHeader
|
|
66
|
+
from basstler.standard_streams import StandardStreamHandler
|
|
67
|
+
from basstler.text_file import TextFile
|
|
68
|
+
|
|
69
|
+
logger = StandardStreamHandler.logger_for(__name__)
|
|
70
|
+
"""
|
|
71
|
+
This module's logger, which is also what its command prints through.
|
|
72
|
+
"""
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
class SiteFile(StrEnum):
|
|
76
|
+
"""
|
|
77
|
+
The files the site writes beside its pages.
|
|
78
|
+
"""
|
|
79
|
+
|
|
80
|
+
PAGE = "index.html"
|
|
81
|
+
"""
|
|
82
|
+
The page a directory serves, for the hub, every index and every plan alike.
|
|
83
|
+
"""
|
|
84
|
+
|
|
85
|
+
NO_JEKYLL = ".nojekyll"
|
|
86
|
+
"""
|
|
87
|
+
The marker that stops GitHub Pages from running Jekyll over already-rendered HTML.
|
|
88
|
+
"""
|
|
89
|
+
|
|
90
|
+
DIGEST = "site-digest.txt"
|
|
91
|
+
"""
|
|
92
|
+
The site's :class:`SiteDigest`, which a deploy compares with the published one.
|
|
93
|
+
"""
|
|
94
|
+
|
|
95
|
+
STYLESHEET = "site.css"
|
|
96
|
+
"""
|
|
97
|
+
The one stylesheet every page links, at the site's root.
|
|
98
|
+
"""
|
|
99
|
+
|
|
100
|
+
|
|
101
|
+
BUILD_TIME_PATTERN = re.compile(
|
|
102
|
+
rf"<time [^>]*{PlanTimeAttribute.REFRESHED}[^>]*>[^<]*</time>".encode()
|
|
103
|
+
)
|
|
104
|
+
"""
|
|
105
|
+
The element a plan page shows the build time in.
|
|
106
|
+
"""
|
|
107
|
+
|
|
108
|
+
|
|
109
|
+
@dataclass(frozen=True)
|
|
110
|
+
class SiteDigest:
|
|
111
|
+
"""
|
|
112
|
+
A fingerprint of a built site's pages: two builds have the same digest exactly when
|
|
113
|
+
they publish the same files with the same content, apart from the build time.
|
|
114
|
+
"""
|
|
115
|
+
|
|
116
|
+
site_directory: Path
|
|
117
|
+
"""
|
|
118
|
+
The root directory the site was built into.
|
|
119
|
+
"""
|
|
120
|
+
|
|
121
|
+
@property
|
|
122
|
+
def value(self) -> str:
|
|
123
|
+
"""
|
|
124
|
+
The fingerprint, as a hexadecimal SHA-256, leaving out :attr:`SiteFile.DIGEST`.
|
|
125
|
+
"""
|
|
126
|
+
digest = hashlib.sha256()
|
|
127
|
+
for path in sorted(self.site_directory.rglob("*")):
|
|
128
|
+
relative_path = path.relative_to(self.site_directory)
|
|
129
|
+
if not path.is_file() or relative_path == Path(SiteFile.DIGEST):
|
|
130
|
+
continue
|
|
131
|
+
digest.update(relative_path.as_posix().encode())
|
|
132
|
+
digest.update(hashlib.sha256(self.content_of(path)).digest())
|
|
133
|
+
return digest.hexdigest()
|
|
134
|
+
|
|
135
|
+
@staticmethod
|
|
136
|
+
def content_of(path: Path) -> bytes:
|
|
137
|
+
"""
|
|
138
|
+
:param path: A built file.
|
|
139
|
+
:return: Its content without the build time, so a build that changed nothing
|
|
140
|
+
else has the published digest and skips the deploy.
|
|
141
|
+
"""
|
|
142
|
+
return BUILD_TIME_PATTERN.sub(b"", path.read_bytes())
|
|
143
|
+
|
|
144
|
+
def write(self) -> None:
|
|
145
|
+
"""
|
|
146
|
+
Write :attr:`value` to the site's :attr:`SiteFile.DIGEST`.
|
|
147
|
+
"""
|
|
148
|
+
TextFile(self.site_directory / SiteFile.DIGEST).write(f"{self.value}\n")
|
|
149
|
+
|
|
150
|
+
|
|
151
|
+
# %% a plan as the notes branch stores it
|
|
152
|
+
|
|
153
|
+
|
|
154
|
+
@dataclass
|
|
155
|
+
class PlanSource:
|
|
156
|
+
"""
|
|
157
|
+
One plan's manifest and roadmap, as read from its directory on the notes branch.
|
|
158
|
+
"""
|
|
159
|
+
|
|
160
|
+
directory_name: str
|
|
161
|
+
"""
|
|
162
|
+
The plan's directory name, which is also the path its page is published under.
|
|
163
|
+
"""
|
|
164
|
+
|
|
165
|
+
manifest: dict[str, Any]
|
|
166
|
+
"""
|
|
167
|
+
The parsed ``plan.yaml``, not yet validated.
|
|
168
|
+
"""
|
|
169
|
+
|
|
170
|
+
roadmap_text: str
|
|
171
|
+
"""
|
|
172
|
+
The plan's ``roadmap.md``, or an empty string if it has none.
|
|
173
|
+
"""
|
|
174
|
+
|
|
175
|
+
@classmethod
|
|
176
|
+
def from_directory(cls, directory: Path) -> PlanSource:
|
|
177
|
+
"""
|
|
178
|
+
Read one plan's directory.
|
|
179
|
+
|
|
180
|
+
:param directory: The directory holding the plan's manifest.
|
|
181
|
+
:return: The plan's source.
|
|
182
|
+
"""
|
|
183
|
+
roadmap = directory / PlanDocument.ROADMAP
|
|
184
|
+
return cls(
|
|
185
|
+
directory_name=directory.name,
|
|
186
|
+
manifest=yaml.safe_load(TextFile(directory / PlanDocument.MANIFEST).read()),
|
|
187
|
+
roadmap_text=TextFile(roadmap).read() if roadmap.exists() else "",
|
|
188
|
+
)
|
|
189
|
+
|
|
190
|
+
@classmethod
|
|
191
|
+
def every_plan_in(cls, plans_directory: Path) -> list[PlanSource]:
|
|
192
|
+
"""
|
|
193
|
+
Read every plan under a ``plans`` directory, in directory-name order.
|
|
194
|
+
|
|
195
|
+
:param plans_directory: The directory holding one subdirectory per plan.
|
|
196
|
+
:return: Each subdirectory that carries a manifest.
|
|
197
|
+
"""
|
|
198
|
+
return [
|
|
199
|
+
cls.from_directory(manifest.parent)
|
|
200
|
+
for manifest in sorted(plans_directory.glob(f"*/{PlanDocument.MANIFEST}"))
|
|
201
|
+
]
|
|
202
|
+
|
|
203
|
+
|
|
204
|
+
# %% the site
|
|
205
|
+
|
|
206
|
+
|
|
207
|
+
@dataclass
|
|
208
|
+
class PublishedPlan:
|
|
209
|
+
"""
|
|
210
|
+
One plan rendered to its page, with the entry the index lists it under.
|
|
211
|
+
"""
|
|
212
|
+
|
|
213
|
+
page: RenderedPlanPage
|
|
214
|
+
"""
|
|
215
|
+
The plan's rendered page.
|
|
216
|
+
"""
|
|
217
|
+
|
|
218
|
+
summary: PlanSummary
|
|
219
|
+
"""
|
|
220
|
+
The plan's card on its repository's index.
|
|
221
|
+
"""
|
|
222
|
+
|
|
223
|
+
|
|
224
|
+
@dataclass
|
|
225
|
+
class SiteSection[SectionCard: ProgressCard](ABC):
|
|
226
|
+
"""
|
|
227
|
+
One part of the site: the pages it writes under the site's root, and the card that
|
|
228
|
+
stands for it on the page above: a repository's on the hub, or the whole site's.
|
|
229
|
+
"""
|
|
230
|
+
|
|
231
|
+
address: SiteAddress
|
|
232
|
+
"""
|
|
233
|
+
The address the whole site is served from, which every link is built on.
|
|
234
|
+
"""
|
|
235
|
+
|
|
236
|
+
pull_request_source: PullRequestSource
|
|
237
|
+
"""
|
|
238
|
+
Where the live pull request state comes from.
|
|
239
|
+
"""
|
|
240
|
+
|
|
241
|
+
built_at: datetime = field(default_factory=lambda: datetime.now(UTC), kw_only=True)
|
|
242
|
+
"""
|
|
243
|
+
When the site is built, which every plan page shows as its last refresh.
|
|
244
|
+
"""
|
|
245
|
+
|
|
246
|
+
@property
|
|
247
|
+
def stylesheet_url(self) -> str:
|
|
248
|
+
"""
|
|
249
|
+
The address of the site's one stylesheet, which every page links.
|
|
250
|
+
"""
|
|
251
|
+
return f"{self.address.hub_url}{SiteFile.STYLESHEET}"
|
|
252
|
+
|
|
253
|
+
@abstractmethod
|
|
254
|
+
def build(self, output: Path) -> SectionCard:
|
|
255
|
+
"""
|
|
256
|
+
Render this part of the site.
|
|
257
|
+
|
|
258
|
+
:param output: The site's root directory.
|
|
259
|
+
:return: The card summing this part up.
|
|
260
|
+
"""
|
|
261
|
+
|
|
262
|
+
@staticmethod
|
|
263
|
+
def write_page(directory: Path, html: str) -> None:
|
|
264
|
+
"""
|
|
265
|
+
:param directory: The directory the page is served from.
|
|
266
|
+
:param html: The page's rendered HTML.
|
|
267
|
+
"""
|
|
268
|
+
directory.mkdir(parents=True, exist_ok=True)
|
|
269
|
+
TextFile(directory / SiteFile.PAGE).write(html)
|
|
270
|
+
|
|
271
|
+
|
|
272
|
+
@dataclass
|
|
273
|
+
class RepositorySite(SiteSection[RepositorySummary]):
|
|
274
|
+
"""
|
|
275
|
+
One repository's plans: their pages plus the index linking them.
|
|
276
|
+
"""
|
|
277
|
+
|
|
278
|
+
notes: NotesBranch
|
|
279
|
+
"""
|
|
280
|
+
The repository's notes branch, which holds and dates its plans.
|
|
281
|
+
"""
|
|
282
|
+
|
|
283
|
+
plans_directory: Path = field(init=False)
|
|
284
|
+
"""
|
|
285
|
+
The notes branch's ``plans`` directory, checked out with one subdirectory per plan.
|
|
286
|
+
"""
|
|
287
|
+
|
|
288
|
+
plan_directory: PlanDirectory = field(init=False)
|
|
289
|
+
"""
|
|
290
|
+
The same plans, as the ``<plan-id>/<item-id>`` entries of any one of them resolve
|
|
291
|
+
against.
|
|
292
|
+
"""
|
|
293
|
+
|
|
294
|
+
repository_rules: RepositoryRules = field(init=False)
|
|
295
|
+
"""
|
|
296
|
+
The rules every plan of the repository follows, as its notes branch holds them.
|
|
297
|
+
"""
|
|
298
|
+
|
|
299
|
+
def __post_init__(self) -> None:
|
|
300
|
+
"""
|
|
301
|
+
Check the plans out of the notes branch and load them and the repository's rules.
|
|
302
|
+
"""
|
|
303
|
+
self.plans_directory = self.notes.check_out_plans()
|
|
304
|
+
self.plan_directory = PlanDirectory(self.plans_directory)
|
|
305
|
+
self.repository_rules = RepositoryRules.from_file(
|
|
306
|
+
self.plans_directory / ProjectLocation.PLAN_RULES.name
|
|
307
|
+
)
|
|
308
|
+
|
|
309
|
+
def plan_url(self, directory_name: str) -> str:
|
|
310
|
+
"""
|
|
311
|
+
:param directory_name: The plan's directory name.
|
|
312
|
+
:return: The address its page is served from.
|
|
313
|
+
"""
|
|
314
|
+
return self.address.plan_url(self.notes.repository, directory_name)
|
|
315
|
+
|
|
316
|
+
def build(self, output: Path) -> RepositorySummary:
|
|
317
|
+
"""
|
|
318
|
+
Render this repository's index and plans into the site.
|
|
319
|
+
|
|
320
|
+
:param output: The site's root directory.
|
|
321
|
+
:return: The repository's card on the hub, naming every plan left out.
|
|
322
|
+
"""
|
|
323
|
+
sources = PlanSource.every_plan_in(self.plans_directory)
|
|
324
|
+
skipped = {
|
|
325
|
+
source.directory_name: page
|
|
326
|
+
for source in sources
|
|
327
|
+
if (page := self.skipped_page_of(source)) is not None
|
|
328
|
+
}
|
|
329
|
+
published = {
|
|
330
|
+
source.directory_name: self.publish(source)
|
|
331
|
+
for source in sources
|
|
332
|
+
if source.directory_name not in skipped
|
|
333
|
+
}
|
|
334
|
+
repository_directory = output / str(self.notes.repository)
|
|
335
|
+
for directory_name, plan in published.items():
|
|
336
|
+
self.write_page(repository_directory / directory_name, plan.page.html)
|
|
337
|
+
repository = RepositorySummary.over_plans(
|
|
338
|
+
str(self.notes.repository),
|
|
339
|
+
self.address.repository_url(self.notes.repository),
|
|
340
|
+
[plan.summary for plan in published.values()],
|
|
341
|
+
list(skipped.values()),
|
|
342
|
+
)
|
|
343
|
+
index = RepositoryIndexPage(
|
|
344
|
+
repository, self.address.hub_url, self.stylesheet_url
|
|
345
|
+
)
|
|
346
|
+
self.write_page(repository_directory, index.render())
|
|
347
|
+
return repository
|
|
348
|
+
|
|
349
|
+
def skipped_page_of(self, source: PlanSource) -> SkippedPage | None:
|
|
350
|
+
"""
|
|
351
|
+
:param source: The plan to check.
|
|
352
|
+
:return: Why it is left out of the site, logging it, or ``None`` when its
|
|
353
|
+
manifest passes validation.
|
|
354
|
+
"""
|
|
355
|
+
problems = PlanValidator(source.manifest, self.plan_directory).problems
|
|
356
|
+
if not problems:
|
|
357
|
+
return None
|
|
358
|
+
page = SkippedPage(
|
|
359
|
+
site_path=f"{self.notes.repository}/{source.directory_name}",
|
|
360
|
+
reason=PlanValidationError(problems).error_message(),
|
|
361
|
+
)
|
|
362
|
+
logger.warning(f"{page.site_path} is not published: {page.reason}")
|
|
363
|
+
return page
|
|
364
|
+
|
|
365
|
+
def publish(self, source: PlanSource) -> PublishedPlan:
|
|
366
|
+
"""
|
|
367
|
+
Render one valid plan.
|
|
368
|
+
|
|
369
|
+
:param source: The plan to render.
|
|
370
|
+
:return: Its page and its index entry.
|
|
371
|
+
"""
|
|
372
|
+
plan = Plan.from_mapping(source.manifest)
|
|
373
|
+
dependencies = DependencyResolver(plan, self.plan_directory)
|
|
374
|
+
live_pull_requests = self.pull_request_source.live_pull_requests_of(
|
|
375
|
+
dependencies.pull_request_references
|
|
376
|
+
)
|
|
377
|
+
for repository, failure in live_pull_requests.read_failures.items():
|
|
378
|
+
logger.warning(
|
|
379
|
+
f"{self.notes.repository}/{source.directory_name}: "
|
|
380
|
+
f"{ItemClassifier.access_warning_of(repository, failure)}"
|
|
381
|
+
)
|
|
382
|
+
renderer = PlanPage(
|
|
383
|
+
stylesheet_url=self.stylesheet_url,
|
|
384
|
+
plan=plan,
|
|
385
|
+
roadmap_text=source.roadmap_text,
|
|
386
|
+
repository_rules=self.repository_rules,
|
|
387
|
+
live_pull_requests=live_pull_requests,
|
|
388
|
+
header=PlanPageHeader(
|
|
389
|
+
tracking_url=self.tracking_url_of(plan),
|
|
390
|
+
hub_url=self.address.hub_url,
|
|
391
|
+
index_url=self.address.repository_url(self.notes.repository),
|
|
392
|
+
history=self.notes.history_of(source.directory_name),
|
|
393
|
+
built_at=self.built_at,
|
|
394
|
+
),
|
|
395
|
+
plan_directory=self.plan_directory,
|
|
396
|
+
locate_plan_page=self.plan_url,
|
|
397
|
+
)
|
|
398
|
+
page = renderer.render()
|
|
399
|
+
summary = PlanSummary(
|
|
400
|
+
id=plan.id,
|
|
401
|
+
title=plan.title,
|
|
402
|
+
description=plan.description,
|
|
403
|
+
page_url=self.plan_url(source.directory_name),
|
|
404
|
+
counted_items=CountedItem.from_plan(plan),
|
|
405
|
+
)
|
|
406
|
+
return PublishedPlan(page=page, summary=summary)
|
|
407
|
+
|
|
408
|
+
def tracking_url_of(self, plan: Plan) -> str | None:
|
|
409
|
+
"""
|
|
410
|
+
:param plan: The plan whose tracking issue to link.
|
|
411
|
+
:return: The tracking issue's page, or ``None`` if the plan has none.
|
|
412
|
+
"""
|
|
413
|
+
if plan.tracking_issue is None:
|
|
414
|
+
return None
|
|
415
|
+
return self.pull_request_source.issue_url(
|
|
416
|
+
Repository.parse(plan.default_repository), plan.tracking_issue
|
|
417
|
+
)
|
|
418
|
+
|
|
419
|
+
|
|
420
|
+
@dataclass
|
|
421
|
+
class HubSite(SiteSection[SiteSummary]):
|
|
422
|
+
"""
|
|
423
|
+
The whole site: the hub page over every repository the hub file lists.
|
|
424
|
+
"""
|
|
425
|
+
|
|
426
|
+
hub: PlanHub
|
|
427
|
+
"""
|
|
428
|
+
The hub file, naming the repositories to publish.
|
|
429
|
+
"""
|
|
430
|
+
|
|
431
|
+
remote_root: str = GitHubAddress.WEB.value
|
|
432
|
+
"""
|
|
433
|
+
Where the listed repositories are fetched from, as
|
|
434
|
+
:meth:`Repository.clone_url_under` takes it.
|
|
435
|
+
"""
|
|
436
|
+
|
|
437
|
+
def build(self, output: Path) -> SiteSummary:
|
|
438
|
+
"""
|
|
439
|
+
Render every repository, then the hub linking them and the stylesheet every page
|
|
440
|
+
links, then the site's digest.
|
|
441
|
+
|
|
442
|
+
:param output: The directory to write the site into.
|
|
443
|
+
:return: The site's summary, holding every repository's card in the hub file's
|
|
444
|
+
order.
|
|
445
|
+
"""
|
|
446
|
+
with tempfile.TemporaryDirectory() as scratch:
|
|
447
|
+
repositories = [
|
|
448
|
+
self.build_repository(
|
|
449
|
+
Repository.parse(repository), Path(scratch) / str(position), output
|
|
450
|
+
)
|
|
451
|
+
for position, repository in enumerate(self.hub.repositories)
|
|
452
|
+
]
|
|
453
|
+
summary = SiteSummary.over_repositories(repositories)
|
|
454
|
+
self.write_page(output, HubPage(summary, self.stylesheet_url).render())
|
|
455
|
+
TextFile(output / SiteFile.STYLESHEET).write(SiteStylesheet().render())
|
|
456
|
+
(output / SiteFile.NO_JEKYLL).touch()
|
|
457
|
+
SiteDigest(output).write()
|
|
458
|
+
return summary
|
|
459
|
+
|
|
460
|
+
def build_repository(
|
|
461
|
+
self, repository: Repository, scratch: Path, output: Path
|
|
462
|
+
) -> RepositorySummary:
|
|
463
|
+
"""
|
|
464
|
+
:param repository: The repository to publish.
|
|
465
|
+
:param scratch: A directory of its own to fetch the notes into.
|
|
466
|
+
:param output: The site's root directory.
|
|
467
|
+
:return: The repository's card, with an error when its notes cannot be read.
|
|
468
|
+
"""
|
|
469
|
+
notes = NotesBranch.fetch(
|
|
470
|
+
repository, self.hub.notes_branch, self.remote_root, scratch
|
|
471
|
+
)
|
|
472
|
+
if notes is None:
|
|
473
|
+
return RepositorySummary.unreadable(
|
|
474
|
+
str(repository), f"cannot fetch {self.hub.notes_branch}"
|
|
475
|
+
)
|
|
476
|
+
site = RepositorySite(
|
|
477
|
+
address=self.address,
|
|
478
|
+
pull_request_source=self.pull_request_source,
|
|
479
|
+
notes=notes,
|
|
480
|
+
built_at=self.built_at,
|
|
481
|
+
)
|
|
482
|
+
return site.build(output)
|
|
483
|
+
|
|
484
|
+
|
|
485
|
+
def main() -> int:
|
|
486
|
+
"""
|
|
487
|
+
Parse arguments and build the site. See the module docstring for the CLI contract.
|
|
488
|
+
"""
|
|
489
|
+
parser = argparse.ArgumentParser(
|
|
490
|
+
description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter
|
|
491
|
+
)
|
|
492
|
+
parser.add_argument(
|
|
493
|
+
"--registry", required=True, help="The repository whose notes hold the hub file"
|
|
494
|
+
)
|
|
495
|
+
parser.add_argument(
|
|
496
|
+
"--output", required=True, type=Path, help="The directory to write the site to"
|
|
497
|
+
)
|
|
498
|
+
parser.add_argument(
|
|
499
|
+
"--site-url", default=None, help="The site's address, if not the hub file's"
|
|
500
|
+
)
|
|
501
|
+
parser.add_argument(
|
|
502
|
+
"--remote-root",
|
|
503
|
+
default=GitHubAddress.WEB.value,
|
|
504
|
+
help="Where repositories are fetched from, as <root>/<owner>/<repo>.git",
|
|
505
|
+
)
|
|
506
|
+
arguments = parser.parse_args()
|
|
507
|
+
|
|
508
|
+
hub = PlanHub.from_registry(
|
|
509
|
+
Repository.parse(arguments.registry), arguments.remote_root
|
|
510
|
+
)
|
|
511
|
+
if hub is None:
|
|
512
|
+
logger.error(f"{arguments.registry} has no hub file on its notes branch.")
|
|
513
|
+
return 1
|
|
514
|
+
site_url = arguments.site_url or hub.site_url
|
|
515
|
+
if not site_url:
|
|
516
|
+
logger.error("The hub file names no site_url; pass --site-url.")
|
|
517
|
+
return 1
|
|
518
|
+
site = HubSite(
|
|
519
|
+
address=SiteAddress(site_url),
|
|
520
|
+
pull_request_source=GitHubPullRequestSource.from_environment(
|
|
521
|
+
reads_mergeable_states=True
|
|
522
|
+
),
|
|
523
|
+
hub=hub,
|
|
524
|
+
remote_root=arguments.remote_root,
|
|
525
|
+
)
|
|
526
|
+
summary = site.build(arguments.output)
|
|
527
|
+
logger.info(f"published {summary.progress_label} to {arguments.output}")
|
|
528
|
+
return 0
|
|
529
|
+
|
|
530
|
+
|
|
531
|
+
if __name__ == "__main__":
|
|
532
|
+
sys.exit(main())
|