@intellectual-frontiers/docs 0.0.0-stage → 0.2.0
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.
- package/LICENSE +75 -0
- package/README.md +8 -2
- package/dist/build.d.ts +63 -0
- package/dist/build.js +103 -0
- package/dist/check.d.ts +63 -0
- package/dist/check.js +54 -0
- package/dist/cli.d.ts +51 -0
- package/dist/cli.js +165 -0
- package/dist/config.d.ts +196 -0
- package/dist/config.js +229 -0
- package/dist/emit/html.d.ts +67 -0
- package/dist/emit/html.js +338 -0
- package/dist/emit/markdown.d.ts +19 -0
- package/dist/emit/markdown.js +124 -0
- package/dist/emit/search.d.ts +15 -0
- package/dist/emit/search.js +29 -0
- package/dist/extract/api.d.ts +74 -0
- package/dist/extract/api.js +261 -0
- package/dist/extract/specs.d.ts +141 -0
- package/dist/extract/specs.js +208 -0
- package/dist/highlight.d.ts +22 -0
- package/dist/highlight.js +77 -0
- package/dist/layered.d.ts +94 -0
- package/dist/layered.js +14 -0
- package/dist/lens/guides.d.ts +23 -0
- package/dist/lens/guides.js +49 -0
- package/dist/lens/layered.d.ts +16 -0
- package/dist/lens/layered.js +354 -0
- package/dist/lens/program.d.ts +23 -0
- package/dist/lens/program.js +124 -0
- package/dist/lens/releases.d.ts +10 -0
- package/dist/lens/releases.js +37 -0
- package/dist/lens.d.ts +30 -0
- package/dist/lens.js +1 -0
- package/dist/links.d.ts +96 -0
- package/dist/links.js +182 -0
- package/dist/main.d.ts +1 -0
- package/dist/main.js +12 -0
- package/dist/markdown.d.ts +43 -0
- package/dist/markdown.js +301 -0
- package/dist/mod.d.ts +32 -0
- package/dist/mod.js +9 -0
- package/dist/model.d.ts +159 -0
- package/dist/model.js +39 -0
- package/dist/pages/api.d.ts +41 -0
- package/dist/pages/api.js +162 -0
- package/dist/pages/areas.d.ts +39 -0
- package/dist/pages/areas.js +119 -0
- package/dist/pages/overview.d.ts +24 -0
- package/dist/pages/overview.js +283 -0
- package/dist/pages/specs.d.ts +31 -0
- package/dist/pages/specs.js +358 -0
- package/dist/site.d.ts +31 -0
- package/dist/site.js +288 -0
- package/dist/sources.d.ts +53 -0
- package/dist/sources.js +159 -0
- package/dist/theme/site.css +275 -0
- package/dist/theme/site.js +174 -0
- package/dist/tsdoc.d.ts +67 -0
- package/dist/tsdoc.js +94 -0
- package/ifc-docs.mjs +4 -0
- package/package.json +66 -4
- package/src/build.ts +117 -0
- package/src/check.ts +84 -0
- package/src/cli.ts +145 -0
- package/src/config.ts +370 -0
- package/src/emit/html.ts +398 -0
- package/src/emit/markdown.ts +129 -0
- package/src/emit/search.ts +38 -0
- package/src/extract/api.ts +297 -0
- package/src/extract/specs.ts +299 -0
- package/src/highlight.ts +98 -0
- package/src/layered.ts +102 -0
- package/src/lens/guides.ts +70 -0
- package/src/lens/layered.ts +341 -0
- package/src/lens/program.ts +137 -0
- package/src/lens/releases.ts +54 -0
- package/src/lens.ts +34 -0
- package/src/links.ts +234 -0
- package/src/main.ts +12 -0
- package/src/markdown.ts +320 -0
- package/src/mod.ts +53 -0
- package/src/model.ts +154 -0
- package/src/pages/api.ts +179 -0
- package/src/pages/areas.ts +133 -0
- package/src/pages/overview.ts +276 -0
- package/src/pages/specs.ts +366 -0
- package/src/site.ts +285 -0
- package/src/sources.ts +157 -0
- package/src/theme/site.css +275 -0
- package/src/theme/site.js +174 -0
- package/src/tsdoc.ts +131 -0
package/dist/mod.js
ADDED
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
export { isAbout, normalDir, resolveConfig, under } from "./config.js";
|
|
2
|
+
export { Build } from "./build.js";
|
|
3
|
+
export { message, report } from "./check.js";
|
|
4
|
+
export { llmsIndex, markdownOf, twinOf } from "./emit/markdown.js";
|
|
5
|
+
export { plain, possessive, slugOf } from "./model.js";
|
|
6
|
+
export { areaPage, firstSentence } from "./pages/overview.js";
|
|
7
|
+
export { moduleComment } from "./tsdoc.js";
|
|
8
|
+
export { buildSite, writeSite } from "./site.js";
|
|
9
|
+
export { findConfig, loadConfig, main, parseArgs, USAGE } from "./cli.js";
|
package/dist/model.d.ts
ADDED
|
@@ -0,0 +1,159 @@
|
|
|
1
|
+
/** Where a link goes: a page of the site (by its path from the site's root), or an address outside it. */
|
|
2
|
+
export type Href = {
|
|
3
|
+
readonly kind: "page";
|
|
4
|
+
readonly path: string;
|
|
5
|
+
readonly anchor?: string;
|
|
6
|
+
} | {
|
|
7
|
+
readonly kind: "external";
|
|
8
|
+
readonly url: string;
|
|
9
|
+
};
|
|
10
|
+
/** A run of text inside a block. */
|
|
11
|
+
export type Inline = {
|
|
12
|
+
readonly kind: "text";
|
|
13
|
+
readonly text: string;
|
|
14
|
+
} | {
|
|
15
|
+
readonly kind: "code";
|
|
16
|
+
readonly text: string;
|
|
17
|
+
} | {
|
|
18
|
+
readonly kind: "emphasis";
|
|
19
|
+
readonly children: readonly Inline[];
|
|
20
|
+
} | {
|
|
21
|
+
readonly kind: "strong";
|
|
22
|
+
readonly children: readonly Inline[];
|
|
23
|
+
} | {
|
|
24
|
+
readonly kind: "link";
|
|
25
|
+
readonly href: Href;
|
|
26
|
+
readonly children: readonly Inline[];
|
|
27
|
+
};
|
|
28
|
+
/** The languages the highlighter knows; anything else is shown as plain text. */
|
|
29
|
+
export type Lang = "ts" | "sql" | "sh" | "toml" | "json" | "turtle" | "yaml" | "mermaid" | "text";
|
|
30
|
+
/** A colour of a badge: neutral, or one that says how something stands. */
|
|
31
|
+
export type Tone = "neutral" | "good" | "warn" | "info";
|
|
32
|
+
/** A small label beside a title: a kind, a status, a mechanism. */
|
|
33
|
+
export interface Badge {
|
|
34
|
+
/** What it says. */
|
|
35
|
+
readonly text: string;
|
|
36
|
+
/** Its colour. */
|
|
37
|
+
readonly tone: Tone;
|
|
38
|
+
}
|
|
39
|
+
/** A card: a title that links somewhere, with a line under it. */
|
|
40
|
+
export interface Card {
|
|
41
|
+
/** The title. */
|
|
42
|
+
readonly title: string;
|
|
43
|
+
/** Where it goes. */
|
|
44
|
+
readonly href: Href;
|
|
45
|
+
/** The line under the title. */
|
|
46
|
+
readonly text: readonly Inline[];
|
|
47
|
+
/** Badges beside the title. */
|
|
48
|
+
readonly badges?: readonly Badge[];
|
|
49
|
+
/** Cards shown under this one, a level in. */
|
|
50
|
+
readonly children?: readonly Card[];
|
|
51
|
+
}
|
|
52
|
+
/** A node of a tree diagram: a label, a note, and what is under it. */
|
|
53
|
+
export interface TreeNode {
|
|
54
|
+
/** What the node is called, as code. */
|
|
55
|
+
readonly label: string;
|
|
56
|
+
/** A short note beside it. */
|
|
57
|
+
readonly note?: readonly Inline[];
|
|
58
|
+
/** The nodes under it. */
|
|
59
|
+
readonly children: readonly TreeNode[];
|
|
60
|
+
}
|
|
61
|
+
/** A tab of a set of tabs. */
|
|
62
|
+
export interface Tab {
|
|
63
|
+
/** Its label. */
|
|
64
|
+
readonly label: string;
|
|
65
|
+
/** What it shows. */
|
|
66
|
+
readonly blocks: readonly Block[];
|
|
67
|
+
}
|
|
68
|
+
/** A part of a page. */
|
|
69
|
+
export type Block = {
|
|
70
|
+
readonly kind: "heading";
|
|
71
|
+
readonly level: 2 | 3 | 4;
|
|
72
|
+
readonly id: string;
|
|
73
|
+
readonly text: readonly Inline[];
|
|
74
|
+
} | {
|
|
75
|
+
readonly kind: "paragraph";
|
|
76
|
+
readonly inlines: readonly Inline[];
|
|
77
|
+
} | {
|
|
78
|
+
readonly kind: "meta";
|
|
79
|
+
readonly inlines: readonly Inline[];
|
|
80
|
+
} | {
|
|
81
|
+
readonly kind: "list";
|
|
82
|
+
readonly ordered: boolean;
|
|
83
|
+
readonly items: readonly (readonly Block[])[];
|
|
84
|
+
} | {
|
|
85
|
+
readonly kind: "code";
|
|
86
|
+
readonly lang: Lang;
|
|
87
|
+
readonly text: string;
|
|
88
|
+
readonly title?: string;
|
|
89
|
+
} | {
|
|
90
|
+
readonly kind: "table";
|
|
91
|
+
readonly head: readonly (readonly Inline[])[];
|
|
92
|
+
readonly rows: readonly (readonly (readonly Inline[])[])[];
|
|
93
|
+
readonly filter?: string;
|
|
94
|
+
readonly compact?: boolean;
|
|
95
|
+
} | {
|
|
96
|
+
readonly kind: "callout";
|
|
97
|
+
readonly tone: "note" | "limit" | "warn";
|
|
98
|
+
readonly title: string;
|
|
99
|
+
readonly blocks: readonly Block[];
|
|
100
|
+
} | {
|
|
101
|
+
readonly kind: "entry";
|
|
102
|
+
readonly id: string;
|
|
103
|
+
readonly name: string;
|
|
104
|
+
readonly badges: readonly Badge[];
|
|
105
|
+
readonly signature?: string;
|
|
106
|
+
readonly blocks: readonly Block[];
|
|
107
|
+
} | {
|
|
108
|
+
readonly kind: "tabs";
|
|
109
|
+
readonly id: string;
|
|
110
|
+
readonly tabs: readonly Tab[];
|
|
111
|
+
} | {
|
|
112
|
+
readonly kind: "diagram";
|
|
113
|
+
readonly source: string;
|
|
114
|
+
readonly caption: string;
|
|
115
|
+
} | {
|
|
116
|
+
readonly kind: "cards";
|
|
117
|
+
readonly cards: readonly Card[];
|
|
118
|
+
} | {
|
|
119
|
+
readonly kind: "badges";
|
|
120
|
+
readonly badges: readonly Badge[];
|
|
121
|
+
} | {
|
|
122
|
+
readonly kind: "tree";
|
|
123
|
+
readonly nodes: readonly TreeNode[];
|
|
124
|
+
};
|
|
125
|
+
/** The sections of the site (commons 0011-documentation FR-009 and FR-032): the guides, the concepts, the libraries, the how-to pages, and the reference (specifications, API and models). */
|
|
126
|
+
export type Section = "start" | "concepts" | "overview" | "howto" | "specs" | "api" | "models" | "programs";
|
|
127
|
+
/** A page: where it is, what it is called, which section and group of the navigation it is in, and its blocks. */
|
|
128
|
+
export interface Page {
|
|
129
|
+
/** Its path from the site's root, ending in `.html`. */
|
|
130
|
+
readonly path: string;
|
|
131
|
+
/** Its title. */
|
|
132
|
+
readonly title: string;
|
|
133
|
+
/** A sentence that says what it is, for the search and the page's description. */
|
|
134
|
+
readonly description: string;
|
|
135
|
+
/** Its section. */
|
|
136
|
+
readonly section: Section;
|
|
137
|
+
/** Its group in the section's navigation. */
|
|
138
|
+
readonly group: string;
|
|
139
|
+
/** Its place in the group: lower first, then by title. */
|
|
140
|
+
readonly order: number;
|
|
141
|
+
/** What the navigation calls it, where that is not its title. */
|
|
142
|
+
readonly navTitle?: string;
|
|
143
|
+
/** The page it is under in the navigation (its path): it is listed beneath that page, and only while that page or a page beneath it is the one being read. */
|
|
144
|
+
readonly parent?: string;
|
|
145
|
+
/** What kind of page it is, for the small heading that groups the pages beneath one page in the navigation (`Concepts`, `Code lists`). */
|
|
146
|
+
readonly navKind?: string;
|
|
147
|
+
/** Its badges, beside the title. */
|
|
148
|
+
readonly badges?: readonly Badge[];
|
|
149
|
+
/** What it holds. */
|
|
150
|
+
readonly blocks: readonly Block[];
|
|
151
|
+
}
|
|
152
|
+
/** The text of inlines, with no markup: for a heading's anchor, the search and a page's description. */
|
|
153
|
+
export declare function plain(inlines: readonly Inline[]): string;
|
|
154
|
+
/** A text as one inline. */
|
|
155
|
+
export declare const text: (t: string) => Inline;
|
|
156
|
+
/** An anchor made from a text: lower-case letters, digits and hyphens. */
|
|
157
|
+
export declare function slugOf(t: string): string;
|
|
158
|
+
/** A name as a possessive: `commons'`, `Stolos'`, `Erga's`. */
|
|
159
|
+
export declare const possessive: (name: string) => string;
|
package/dist/model.js
ADDED
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
// Spec: 0001-docs FR-001
|
|
2
|
+
/**
|
|
3
|
+
* The page model (commons 0011-documentation FR-016): every page of the site is a value of these types before it is HTML. Readers (the
|
|
4
|
+
* Markdown of TSDoc and of specifications, the API reader, the lenses) make blocks and inlines; the HTML emitter is the one writer, and
|
|
5
|
+
* matches every case with a `switch` that ends in `absurd`, so that a case added here and left out there does not compile.
|
|
6
|
+
*
|
|
7
|
+
* @module
|
|
8
|
+
*/
|
|
9
|
+
import { absurd } from "@intellectual-frontiers/core";
|
|
10
|
+
/** The text of inlines, with no markup: for a heading's anchor, the search and a page's description. */
|
|
11
|
+
export function plain(inlines) {
|
|
12
|
+
return inlines
|
|
13
|
+
.map((i) => {
|
|
14
|
+
switch (i.kind) {
|
|
15
|
+
case "text":
|
|
16
|
+
case "code":
|
|
17
|
+
return i.text;
|
|
18
|
+
case "emphasis":
|
|
19
|
+
case "strong":
|
|
20
|
+
case "link":
|
|
21
|
+
return plain(i.children);
|
|
22
|
+
default:
|
|
23
|
+
return absurd(i);
|
|
24
|
+
}
|
|
25
|
+
})
|
|
26
|
+
.join("");
|
|
27
|
+
}
|
|
28
|
+
/** A text as one inline. */
|
|
29
|
+
export const text = (t) => ({ kind: "text", text: t });
|
|
30
|
+
/** An anchor made from a text: lower-case letters, digits and hyphens. */
|
|
31
|
+
export function slugOf(t) {
|
|
32
|
+
return t
|
|
33
|
+
.toLowerCase()
|
|
34
|
+
.normalize("NFKD")
|
|
35
|
+
.replace(/[^\p{L}\p{N}]+/gu, "-")
|
|
36
|
+
.replace(/^-+|-+$/g, "");
|
|
37
|
+
}
|
|
38
|
+
/** A name as a possessive: `commons'`, `Stolos'`, `Erga's`. */
|
|
39
|
+
export const possessive = (name) => (name.endsWith("s") ? `${name}'` : `${name}'s`);
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The API pages of each area (commons 0011-documentation FR-010): a page for each source file its exports come from, in the order its
|
|
3
|
+
* entry points export them, with the file's module comment (what it is, its account, its examples, its limits) and an entry for each
|
|
4
|
+
* export: its kinds, its signature, its TSDoc (summary, remarks, parameters, what it returns, examples, see also, deprecation) and the
|
|
5
|
+
* members of an interface. Pages and anchors are registered first, so that every other page's `{@link}` and file links reach them.
|
|
6
|
+
*
|
|
7
|
+
* @module
|
|
8
|
+
*/
|
|
9
|
+
import type { Build } from "../build.js";
|
|
10
|
+
import type { AreaApi } from "../extract/api.js";
|
|
11
|
+
import { type Area } from "../sources.js";
|
|
12
|
+
/** A module page of an area: its page, its title and the first sentence of its module comment. */
|
|
13
|
+
export interface ModulePage {
|
|
14
|
+
/** The page. */
|
|
15
|
+
readonly page: string;
|
|
16
|
+
/** The file, from the checkout's root. */
|
|
17
|
+
readonly file: string;
|
|
18
|
+
/** Its title: the file's path in the area, without `.ts`. */
|
|
19
|
+
readonly title: string;
|
|
20
|
+
/** The first sentence of its module comment. */
|
|
21
|
+
readonly summary: string;
|
|
22
|
+
}
|
|
23
|
+
/** The anchor of an export on its page. */
|
|
24
|
+
export declare const anchorOf: (name: string) => string;
|
|
25
|
+
/**
|
|
26
|
+
* The pages and anchors of every area's API, registered before any page is made.
|
|
27
|
+
*
|
|
28
|
+
* @param b - the build
|
|
29
|
+
* @param areas - the areas
|
|
30
|
+
* @param apis - their APIs
|
|
31
|
+
*/
|
|
32
|
+
export declare function registerApi(b: Build, areas: readonly Area[], apis: readonly AreaApi[]): Map<string, ModulePage[]>;
|
|
33
|
+
/**
|
|
34
|
+
* A page for each source file of each area's exports.
|
|
35
|
+
*
|
|
36
|
+
* @param b - the build
|
|
37
|
+
* @param areas - the areas
|
|
38
|
+
* @param apis - their APIs
|
|
39
|
+
* @param modules - the module pages `registerApi` gave
|
|
40
|
+
*/
|
|
41
|
+
export declare function apiPages(b: Build, areas: readonly Area[], apis: readonly AreaApi[], modules: ReadonlyMap<string, readonly ModulePage[]>): void;
|
|
@@ -0,0 +1,162 @@
|
|
|
1
|
+
import { inside } from "../sources.js";
|
|
2
|
+
import { moduleComment } from "../tsdoc.js";
|
|
3
|
+
import { firstSentence } from "./overview.js";
|
|
4
|
+
/** The anchor of an export on its page. */
|
|
5
|
+
export const anchorOf = (name) => name.replace(/[^\w.-]/g, "-");
|
|
6
|
+
/** The title of a file in an area: its path from the area's folder (or the package's), without `.ts`. */
|
|
7
|
+
function titleOf(area, file) {
|
|
8
|
+
const from = (dir) => (dir === "" ? file : file.slice(dir.length + 1));
|
|
9
|
+
const base = inside(area.dir, file) ? from(area.dir) : inside(area.pkg.dir, file) ? from(area.pkg.dir) : file;
|
|
10
|
+
return base.replace(/\.ts$/, "");
|
|
11
|
+
}
|
|
12
|
+
/** Whether a file is the area's own, or one it re-exports from elsewhere. */
|
|
13
|
+
const own = (area, file) => inside(area.dir, file);
|
|
14
|
+
/** The page of a file of an area; what the area re-exports from elsewhere is on one page. */
|
|
15
|
+
const pageOf = (area, file) => own(area, file) ? `api/${area.slug}/${titleOf(area, file).replace(/\//g, "-")}.html` : `api/${area.slug}/re-exports.html`;
|
|
16
|
+
/** The pages of an area's exports, in the order of their first export, each with its file (none for the re-exports). */
|
|
17
|
+
function pagesOf(area, api) {
|
|
18
|
+
const out = new Map();
|
|
19
|
+
for (const e of api.exports) {
|
|
20
|
+
const page = pageOf(area, e.file);
|
|
21
|
+
if (!out.has(page))
|
|
22
|
+
out.set(page, own(area, e.file) ? e.file : undefined);
|
|
23
|
+
}
|
|
24
|
+
return [...out];
|
|
25
|
+
}
|
|
26
|
+
/**
|
|
27
|
+
* The pages and anchors of every area's API, registered before any page is made.
|
|
28
|
+
*
|
|
29
|
+
* @param b - the build
|
|
30
|
+
* @param areas - the areas
|
|
31
|
+
* @param apis - their APIs
|
|
32
|
+
*/
|
|
33
|
+
export function registerApi(b, areas, apis) {
|
|
34
|
+
const modules = new Map();
|
|
35
|
+
for (const area of areas) {
|
|
36
|
+
const api = apis.find((a) => a.slug === area.slug);
|
|
37
|
+
if (api === undefined)
|
|
38
|
+
continue;
|
|
39
|
+
const names = new Map();
|
|
40
|
+
const list = [];
|
|
41
|
+
for (const [page, file] of pagesOf(area, api)) {
|
|
42
|
+
if (file === undefined) {
|
|
43
|
+
list.push({ page, file: "", title: "re-exports", summary: `What ${area.title} exports from elsewhere, so that its users need import nothing else.` });
|
|
44
|
+
continue;
|
|
45
|
+
}
|
|
46
|
+
if (!b.files.has(file))
|
|
47
|
+
b.files.set(file, page);
|
|
48
|
+
if (!b.apiFiles.has(file))
|
|
49
|
+
b.apiFiles.set(file, page);
|
|
50
|
+
const doc = b.exists(file) ? moduleComment(b.read(file)) : undefined;
|
|
51
|
+
list.push({ page, file, title: titleOf(area, file), summary: doc === undefined ? "" : firstSentence(doc.summary, 200) });
|
|
52
|
+
}
|
|
53
|
+
for (const e of api.exports) {
|
|
54
|
+
const entry = { path: pageOf(area, e.file), anchor: anchorOf(e.name) };
|
|
55
|
+
names.set(e.name, entry);
|
|
56
|
+
const key = `${e.file}#${e.declared ?? e.name.split(".").pop() ?? e.name}`;
|
|
57
|
+
if (own(area, e.file) && !b.declared.has(key))
|
|
58
|
+
b.declared.set(key, entry);
|
|
59
|
+
const short = e.name.split(".").pop();
|
|
60
|
+
if (short !== undefined && !names.has(short))
|
|
61
|
+
names.set(short, entry);
|
|
62
|
+
}
|
|
63
|
+
b.exports.set(area.slug, names);
|
|
64
|
+
modules.set(area.slug, list);
|
|
65
|
+
}
|
|
66
|
+
return modules;
|
|
67
|
+
}
|
|
68
|
+
const textInl = (t) => ({ kind: "text", text: t });
|
|
69
|
+
/** The blocks of an export's entry. */
|
|
70
|
+
function entryBlocks(b, e, scope) {
|
|
71
|
+
const d = e.doc;
|
|
72
|
+
const out = [];
|
|
73
|
+
if (d.deprecated !== undefined)
|
|
74
|
+
out.push({ kind: "callout", tone: "warn", title: "Deprecated", blocks: b.md(d.deprecated, scope) });
|
|
75
|
+
out.push(...b.md(d.summary, scope));
|
|
76
|
+
if (d.remarks !== undefined)
|
|
77
|
+
out.push(...b.md(d.remarks, scope));
|
|
78
|
+
if (d.params.length > 0) {
|
|
79
|
+
out.push({
|
|
80
|
+
kind: "table",
|
|
81
|
+
head: [[textInl("Parameter")], [textInl("What it is")]],
|
|
82
|
+
rows: d.params.map((p) => [[{ kind: "code", text: p.name }], b.line(p.text, scope)]),
|
|
83
|
+
});
|
|
84
|
+
}
|
|
85
|
+
if (d.returns !== undefined)
|
|
86
|
+
out.push({ kind: "paragraph", inlines: [{ kind: "strong", children: [textInl("Returns: ")] }, ...b.line(d.returns, scope)] });
|
|
87
|
+
if (e.members.length > 0) {
|
|
88
|
+
out.push({
|
|
89
|
+
kind: "table",
|
|
90
|
+
head: [[textInl("Member")], [textInl("Type")], [textInl("What it is")]],
|
|
91
|
+
rows: e.members.map((m) => [[{ kind: "code", text: `${m.name}${m.optional ? "?" : ""}` }], [{ kind: "code", text: m.type }], b.line(m.doc, scope)]),
|
|
92
|
+
});
|
|
93
|
+
}
|
|
94
|
+
for (const x of d.examples)
|
|
95
|
+
out.push(...b.example(x, scope));
|
|
96
|
+
if (d.limits !== undefined)
|
|
97
|
+
out.push({ kind: "callout", tone: "limit", title: "Limits", blocks: b.md(d.limits, scope) });
|
|
98
|
+
if (d.see.length > 0) {
|
|
99
|
+
out.push({ kind: "paragraph", inlines: [{ kind: "strong", children: [textInl("See also: ")] }, ...d.see.flatMap((s, i) => [...(i === 0 ? [] : [textInl("; ")]), ...b.line(s, scope)])] });
|
|
100
|
+
}
|
|
101
|
+
return out;
|
|
102
|
+
}
|
|
103
|
+
/**
|
|
104
|
+
* A page for each source file of each area's exports.
|
|
105
|
+
*
|
|
106
|
+
* @param b - the build
|
|
107
|
+
* @param areas - the areas
|
|
108
|
+
* @param apis - their APIs
|
|
109
|
+
* @param modules - the module pages `registerApi` gave
|
|
110
|
+
*/
|
|
111
|
+
export function apiPages(b, areas, apis, modules) {
|
|
112
|
+
areas.forEach((area, ai) => {
|
|
113
|
+
const api = apis.find((a) => a.slug === area.slug);
|
|
114
|
+
if (api === undefined)
|
|
115
|
+
return;
|
|
116
|
+
const spec = area.spec?.id ?? area.pkg.about.spec?.id;
|
|
117
|
+
(modules.get(area.slug) ?? []).forEach((m, mi) => {
|
|
118
|
+
const scope = { page: m.page, file: m.file || (area.dir === "" ? "" : `${area.dir}/`), area: area.slug, ...(spec === undefined ? {} : { spec }) };
|
|
119
|
+
const doc = m.file !== "" && b.exists(m.file) ? moduleComment(b.read(m.file)) : undefined;
|
|
120
|
+
const blocks = [];
|
|
121
|
+
if (doc !== undefined) {
|
|
122
|
+
blocks.push(...b.md(doc.summary, scope));
|
|
123
|
+
if (doc.remarks !== undefined)
|
|
124
|
+
blocks.push(...b.md(doc.remarks, scope));
|
|
125
|
+
for (const x of doc.examples)
|
|
126
|
+
blocks.push(...b.example(x, scope));
|
|
127
|
+
if (doc.limits !== undefined)
|
|
128
|
+
blocks.push({ kind: "callout", tone: "limit", title: "Limits", blocks: b.md(doc.limits, scope) });
|
|
129
|
+
}
|
|
130
|
+
if (m.file === "")
|
|
131
|
+
blocks.push({ kind: "paragraph", inlines: [textInl(m.summary)] });
|
|
132
|
+
else
|
|
133
|
+
blocks.push({ kind: "meta", inlines: [textInl("Source: "), { kind: "link", href: { kind: "external", url: b.index.blob(m.file) }, children: [{ kind: "code", text: m.file }] }] });
|
|
134
|
+
for (const e of api.exports.filter((x) => pageOf(area, x.file) === m.page)) {
|
|
135
|
+
if (!e.documented)
|
|
136
|
+
b.found.push({ where: `${m.file} (${area.slug})`, problem: { kind: "undocumented", name: e.name } });
|
|
137
|
+
const badges = e.kinds.map((k) => ({ text: k, tone: "neutral" }));
|
|
138
|
+
const at = b.declared.get(`${e.file}#${e.declared ?? e.name.split(".").pop() ?? e.name}`);
|
|
139
|
+
const home = b.apiFiles.get(e.file) ?? b.files.get(e.file);
|
|
140
|
+
const target = at ?? (home === undefined ? undefined : { path: home, anchor: anchorOf(e.name) });
|
|
141
|
+
const declared = m.file === ""
|
|
142
|
+
? [{ kind: "meta", inlines: [textInl("Declared in "), target === undefined ? { kind: "code", text: e.file } : { kind: "link", href: { kind: "page", ...target }, children: [{ kind: "code", text: e.file }] }] }]
|
|
143
|
+
: [];
|
|
144
|
+
const shown = b.entityPages.get(`${area.slug}!${e.name}`);
|
|
145
|
+
const model = shown === undefined
|
|
146
|
+
? []
|
|
147
|
+
: [{ kind: "meta", inlines: [textInl("A table of the model: "), { kind: "link", href: { kind: "page", path: shown }, children: [textInl("columns, diagram, SQL and governance")] }] }];
|
|
148
|
+
const body = e.kinds.includes("namespace") ? [] : [...declared, ...model, ...entryBlocks(b, e, { ...scope, file: e.file })];
|
|
149
|
+
blocks.push({ kind: "entry", id: anchorOf(e.name), name: e.name, badges, signature: e.signature, blocks: body });
|
|
150
|
+
}
|
|
151
|
+
b.add({
|
|
152
|
+
path: m.page,
|
|
153
|
+
title: m.title,
|
|
154
|
+
description: m.summary || `${area.title}: ${m.title}`,
|
|
155
|
+
section: "api",
|
|
156
|
+
group: area.title,
|
|
157
|
+
order: 100 + ai * 100 + mi + 1,
|
|
158
|
+
blocks,
|
|
159
|
+
});
|
|
160
|
+
});
|
|
161
|
+
});
|
|
162
|
+
}
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The overview of each area (commons 0011-documentation FR-009): the module comment of its first entry point (what the area is, its
|
|
3
|
+
* longer account and its examples), its entry points, its phases, its examples as the compiler checks them, and the limits of every
|
|
4
|
+
* module of the area, gathered from their `@limits`, each under the file it is about.
|
|
5
|
+
*
|
|
6
|
+
* @module
|
|
7
|
+
*/
|
|
8
|
+
import type { Build } from "../build.js";
|
|
9
|
+
import type { LinkScope } from "../links.js";
|
|
10
|
+
import type { Block } from "../model.js";
|
|
11
|
+
import type { Area } from "../sources.js";
|
|
12
|
+
import type { ModulePage } from "./api.js";
|
|
13
|
+
/**
|
|
14
|
+
* How a file is named on a page: its path from the outermost package that holds it (`arca/party.ts` in commons' `commons/data`), or
|
|
15
|
+
* from the root where no package does.
|
|
16
|
+
*
|
|
17
|
+
* @param b - the build
|
|
18
|
+
* @param file - the file, from the root
|
|
19
|
+
*/
|
|
20
|
+
export declare function shownPath(b: Build, file: string): string;
|
|
21
|
+
/**
|
|
22
|
+
* An example file as the site shows it: a heading that names it, what it shows, its module comment as prose, and its code without the
|
|
23
|
+
* comment.
|
|
24
|
+
*
|
|
25
|
+
* @param b - the build
|
|
26
|
+
* @param file - the file, from the checkout's root
|
|
27
|
+
* @param shown - its name as the heading shows it
|
|
28
|
+
* @param what - what it shows
|
|
29
|
+
* @param scope - where the words are
|
|
30
|
+
*/
|
|
31
|
+
export declare function exampleBlocks(b: Build, file: string, shown: string, what: string, scope: LinkScope): Block[];
|
|
32
|
+
/**
|
|
33
|
+
* The overview page of each area, after the API's pages, so that a limit links to the page of its file.
|
|
34
|
+
*
|
|
35
|
+
* @param b - the build
|
|
36
|
+
* @param areas - the areas
|
|
37
|
+
* @param modules - the module pages of each area
|
|
38
|
+
*/
|
|
39
|
+
export declare function areaPages(b: Build, areas: readonly Area[], modules: ReadonlyMap<string, readonly ModulePage[]>): void;
|
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
import { under } from "../config.js";
|
|
2
|
+
import { areaFiles, inside } from "../sources.js";
|
|
3
|
+
import { moduleComment } from "../tsdoc.js";
|
|
4
|
+
import { areaPage, firstSentence } from "./overview.js";
|
|
5
|
+
import { numberOf } from "./specs.js";
|
|
6
|
+
/**
|
|
7
|
+
* How a file is named on a page: its path from the outermost package that holds it (`arca/party.ts` in commons' `commons/data`), or
|
|
8
|
+
* from the root where no package does.
|
|
9
|
+
*
|
|
10
|
+
* @param b - the build
|
|
11
|
+
* @param file - the file, from the root
|
|
12
|
+
*/
|
|
13
|
+
export function shownPath(b, file) {
|
|
14
|
+
const dirs = b.config.packages.map((p) => p.dir).filter((d) => d !== "" && inside(d, file)).sort((x, y) => x.length - y.length);
|
|
15
|
+
const outer = dirs[0];
|
|
16
|
+
return outer === undefined ? file : file.slice(outer.length + 1);
|
|
17
|
+
}
|
|
18
|
+
/** Where a file of an area is shown: its page of the API where there is one, else its overview. */
|
|
19
|
+
const fileLink = (b, file, fallback) => ({
|
|
20
|
+
kind: "link",
|
|
21
|
+
href: { kind: "page", path: b.files.get(file) ?? fallback },
|
|
22
|
+
children: [{ kind: "code", text: shownPath(b, file) }],
|
|
23
|
+
});
|
|
24
|
+
const heading = (id, t) => ({ kind: "heading", level: 2, id, text: [{ kind: "text", text: t }] });
|
|
25
|
+
/**
|
|
26
|
+
* An example file as the site shows it: a heading that names it, what it shows, its module comment as prose, and its code without the
|
|
27
|
+
* comment.
|
|
28
|
+
*
|
|
29
|
+
* @param b - the build
|
|
30
|
+
* @param file - the file, from the checkout's root
|
|
31
|
+
* @param shown - its name as the heading shows it
|
|
32
|
+
* @param what - what it shows
|
|
33
|
+
* @param scope - where the words are
|
|
34
|
+
*/
|
|
35
|
+
export function exampleBlocks(b, file, shown, what, scope) {
|
|
36
|
+
const text = b.exists(file) ? b.read(file) : "";
|
|
37
|
+
const doc = moduleComment(text);
|
|
38
|
+
const code = text.replace(/^\s*\/\*\*[\s\S]*?\*\/\s*/, "").trimEnd();
|
|
39
|
+
return [
|
|
40
|
+
{ kind: "heading", level: 3, id: `example-${shown.replace(/\W+/g, "-")}`, text: [{ kind: "text", text: "Example: " }, { kind: "code", text: shown }] },
|
|
41
|
+
{ kind: "paragraph", inlines: b.line(what, scope) },
|
|
42
|
+
...(doc === undefined ? [] : b.md(doc.summary, { ...scope, file })),
|
|
43
|
+
{ kind: "code", lang: "ts", title: shown, text: code },
|
|
44
|
+
];
|
|
45
|
+
}
|
|
46
|
+
/**
|
|
47
|
+
* The overview page of each area, after the API's pages, so that a limit links to the page of its file.
|
|
48
|
+
*
|
|
49
|
+
* @param b - the build
|
|
50
|
+
* @param areas - the areas
|
|
51
|
+
* @param modules - the module pages of each area
|
|
52
|
+
*/
|
|
53
|
+
export function areaPages(b, areas, modules) {
|
|
54
|
+
areas.forEach((area, i) => {
|
|
55
|
+
const page = areaPage(area);
|
|
56
|
+
const entry = under(area.pkg.dir, area.entryPoints[0] ?? "");
|
|
57
|
+
const spec = area.spec?.id ?? area.pkg.about.spec?.id;
|
|
58
|
+
const scope = { page, file: entry, area: area.slug, ...(spec === undefined ? {} : { spec }) };
|
|
59
|
+
const doc = b.exists(entry) ? moduleComment(b.read(entry)) : undefined;
|
|
60
|
+
const blocks = [];
|
|
61
|
+
if (doc !== undefined) {
|
|
62
|
+
blocks.push(...b.md(doc.summary, scope));
|
|
63
|
+
if (doc.remarks !== undefined)
|
|
64
|
+
blocks.push(...b.md(doc.remarks, scope));
|
|
65
|
+
}
|
|
66
|
+
if (area.spec !== undefined) {
|
|
67
|
+
blocks.push({ kind: "paragraph", inlines: [{ kind: "text", text: "Specification: " }, ...b.line(`${area.spec.repo} ${area.spec.id}`, scope)] });
|
|
68
|
+
}
|
|
69
|
+
blocks.push(heading("entry-points", "Entry points"), {
|
|
70
|
+
kind: "list",
|
|
71
|
+
ordered: false,
|
|
72
|
+
items: area.entryPoints.map((e) => [{ kind: "paragraph", inlines: [fileLink(b, under(area.pkg.dir, e), page)] }]),
|
|
73
|
+
});
|
|
74
|
+
const mods = modules.get(area.slug) ?? [];
|
|
75
|
+
if (mods.length > 0) {
|
|
76
|
+
blocks.push(heading("modules", "Modules"), {
|
|
77
|
+
kind: "cards",
|
|
78
|
+
cards: mods.map((m) => ({ title: m.title, href: { kind: "page", path: m.page }, text: b.line(m.summary, { ...scope, file: m.file }) })),
|
|
79
|
+
});
|
|
80
|
+
}
|
|
81
|
+
if ((doc?.examples.length ?? 0) + (area.examples?.length ?? 0) > 0)
|
|
82
|
+
blocks.push(heading("examples", "Examples"));
|
|
83
|
+
for (const x of doc?.examples ?? [])
|
|
84
|
+
blocks.push(...b.example(x, scope));
|
|
85
|
+
for (const x of area.examples ?? [])
|
|
86
|
+
blocks.push(...exampleBlocks(b, under(area.pkg.dir, x.file), x.file, x.what, scope));
|
|
87
|
+
if (area.phases !== undefined && area.phases.length > 0) {
|
|
88
|
+
blocks.push(heading("phases", "Phases"), {
|
|
89
|
+
kind: "table",
|
|
90
|
+
head: ["Phase", "What", "State"].map((h) => [{ kind: "text", text: h }]),
|
|
91
|
+
rows: area.phases.map((p) => [[{ kind: "text", text: String(p.n) }], b.line(p.what, scope), [{ kind: "text", text: p.state }]]),
|
|
92
|
+
});
|
|
93
|
+
}
|
|
94
|
+
const limits = areaFiles(b.root, area.dir)
|
|
95
|
+
.map((f) => [f, moduleComment(b.read(f))?.limits])
|
|
96
|
+
.filter((x) => x[1] !== undefined);
|
|
97
|
+
if (limits.length > 0) {
|
|
98
|
+
blocks.push(heading("limits", "Limits"), {
|
|
99
|
+
kind: "paragraph",
|
|
100
|
+
inlines: [{ kind: "text", text: "What the modules of this area do not do, or do only in part, as each module's @limits says." }],
|
|
101
|
+
});
|
|
102
|
+
for (const [f, text] of limits) {
|
|
103
|
+
const fileScope = { ...scope, file: f };
|
|
104
|
+
blocks.push({ kind: "callout", tone: "limit", title: f.split("/").slice(-2).join("/"), blocks: [{ kind: "paragraph", inlines: [fileLink(b, f, page)] }, ...b.md(text, fileScope)] });
|
|
105
|
+
}
|
|
106
|
+
}
|
|
107
|
+
b.add({
|
|
108
|
+
path: page,
|
|
109
|
+
title: area.title,
|
|
110
|
+
description: doc === undefined ? area.title : firstSentence(doc.summary),
|
|
111
|
+
section: "api",
|
|
112
|
+
group: area.title,
|
|
113
|
+
order: 100 + i * 100,
|
|
114
|
+
navTitle: "Overview",
|
|
115
|
+
...(spec === undefined ? {} : { badges: [{ text: numberOf(spec), tone: "neutral" }] }),
|
|
116
|
+
blocks,
|
|
117
|
+
});
|
|
118
|
+
});
|
|
119
|
+
}
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
import type { Build } from "../build.js";
|
|
2
|
+
import { type Area, type Package } from "../sources.js";
|
|
3
|
+
/** The first sentence of a text, for a card. */
|
|
4
|
+
export declare function firstSentence(t: string, max?: number): string;
|
|
5
|
+
/**
|
|
6
|
+
* What each package imports and what imports it, among the packages of the site: the packages its own sources (not its tests, tools or manifest) import by name, by slug.
|
|
7
|
+
*/
|
|
8
|
+
export declare function dependenciesOf(b: Build, packages: readonly Package[]): {
|
|
9
|
+
readonly uses: ReadonlyMap<string, readonly string[]>;
|
|
10
|
+
readonly usedBy: ReadonlyMap<string, readonly string[]>;
|
|
11
|
+
};
|
|
12
|
+
/** The page of a package. */
|
|
13
|
+
export declare const packagePage: (pkg: Package) => string;
|
|
14
|
+
/** The overview page of an area. */
|
|
15
|
+
export declare const areaPage: (area: Area) => string;
|
|
16
|
+
/**
|
|
17
|
+
* The home page and a page for each package.
|
|
18
|
+
*
|
|
19
|
+
* @param b - the build
|
|
20
|
+
* @param top - the home's package: the repository as a whole
|
|
21
|
+
* @param packages - the packages
|
|
22
|
+
* @param areas - their areas
|
|
23
|
+
*/
|
|
24
|
+
export declare function overviewPages(b: Build, top: Package, packages: readonly Package[], areas: readonly Area[]): void;
|