@jfdevelops/docs 0.0.0 → 0.1.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 +21 -0
- package/README.md +86 -1
- package/dist/check.d.ts +69 -0
- package/dist/check.js +588 -0
- package/dist/cli.d.ts +2 -0
- package/dist/cli.js +84 -0
- package/dist/config.d.ts +17 -0
- package/dist/config.js +51 -0
- package/dist/generate.d.ts +7 -0
- package/dist/generate.js +102 -0
- package/dist/index.d.ts +4 -0
- package/dist/index.js +4 -0
- package/dist/manifest.d.ts +112 -0
- package/dist/manifest.js +214 -0
- package/package.json +44 -3
package/dist/config.js
ADDED
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
import { existsSync, readFileSync } from 'node:fs';
|
|
2
|
+
import path from 'node:path';
|
|
3
|
+
export const addonName = 'docs';
|
|
4
|
+
const optionKeys = ['package', 'name', 'entry', 'tsconfig', 'examples'];
|
|
5
|
+
function isOptionKey(key) {
|
|
6
|
+
return optionKeys.includes(key);
|
|
7
|
+
}
|
|
8
|
+
function titleFromPackageName(name) {
|
|
9
|
+
return (name.split('/').at(-1) ?? name)
|
|
10
|
+
.split('-')
|
|
11
|
+
.map((word) => word.charAt(0).toUpperCase() + word.slice(1))
|
|
12
|
+
.join(' ');
|
|
13
|
+
}
|
|
14
|
+
/** Reads the docs addon options that `jfdevelops add addon docs` records in jfdevelops.json. */
|
|
15
|
+
function readAddonOptions(root) {
|
|
16
|
+
const file = path.join(root, 'jfdevelops.json');
|
|
17
|
+
if (!existsSync(file)) {
|
|
18
|
+
return {};
|
|
19
|
+
}
|
|
20
|
+
const config = JSON.parse(readFileSync(file, 'utf8'));
|
|
21
|
+
return config.addons?.find((entry) => entry.name === addonName)?.options ?? {};
|
|
22
|
+
}
|
|
23
|
+
/**
|
|
24
|
+
* Resolves the docs settings for a project. Explicit overrides win over the addon options in
|
|
25
|
+
* jfdevelops.json, which win over the defaults.
|
|
26
|
+
*/
|
|
27
|
+
export function loadConfig(root, overrides = {}) {
|
|
28
|
+
const options = {};
|
|
29
|
+
for (const [key, value] of Object.entries({ ...readAddonOptions(root), ...overrides })) {
|
|
30
|
+
if (!isOptionKey(key)) {
|
|
31
|
+
throw new Error(`Unknown docs option "${key}". Allowed: ${optionKeys.join(', ')}.`);
|
|
32
|
+
}
|
|
33
|
+
if (value !== undefined && value !== null && value !== '') {
|
|
34
|
+
options[key] = String(value);
|
|
35
|
+
}
|
|
36
|
+
}
|
|
37
|
+
const packageDirectory = options.package ?? '.';
|
|
38
|
+
const manifestFile = path.join(root, packageDirectory, 'package.json');
|
|
39
|
+
if (!existsSync(manifestFile)) {
|
|
40
|
+
throw new Error(`The docs package "${packageDirectory}" has no package.json.`);
|
|
41
|
+
}
|
|
42
|
+
const manifest = JSON.parse(readFileSync(manifestFile, 'utf8'));
|
|
43
|
+
const inPackage = (file) => path.posix.join(packageDirectory, file);
|
|
44
|
+
return {
|
|
45
|
+
package: packageDirectory,
|
|
46
|
+
name: options.name ?? titleFromPackageName(manifest.name ?? path.basename(path.resolve(root, packageDirectory))),
|
|
47
|
+
entry: options.entry ?? inPackage('src/index.ts'),
|
|
48
|
+
tsconfig: options.tsconfig ?? inPackage('tsconfig.json'),
|
|
49
|
+
examples: options.examples ?? '',
|
|
50
|
+
};
|
|
51
|
+
}
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
import { type DocsConfig } from './config.js';
|
|
2
|
+
/** Writes the API reference, docs/docs.json and every meta.json. */
|
|
3
|
+
export declare function generateDocs({ root, config, isReferenceSkipped }: {
|
|
4
|
+
root: string;
|
|
5
|
+
config?: DocsConfig;
|
|
6
|
+
isReferenceSkipped?: boolean;
|
|
7
|
+
}): Promise<void>;
|
package/dist/generate.js
ADDED
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
import { cp, mkdtemp, readdir, readFile, rm, writeFile } from 'node:fs/promises';
|
|
2
|
+
import { createRequire } from 'node:module';
|
|
3
|
+
import { tmpdir } from 'node:os';
|
|
4
|
+
import path from 'node:path';
|
|
5
|
+
import { Application } from 'typedoc';
|
|
6
|
+
import { loadConfig } from './config.js';
|
|
7
|
+
import { listVersions, writeDocsNavigation } from './manifest.js';
|
|
8
|
+
const require = createRequire(import.meta.url);
|
|
9
|
+
// typedoc-plugin-markdown options; the plugin does not add them to TypeDoc's option types.
|
|
10
|
+
const markdownOptions = { entryFileName: 'index', hidePageHeader: true, hidePageTitle: true, hideBreadcrumbs: true, useCodeBlocks: true };
|
|
11
|
+
function toPosix(value) {
|
|
12
|
+
return value.split(path.sep).join('/');
|
|
13
|
+
}
|
|
14
|
+
async function addPageMetadata(directory, isRoot = true) {
|
|
15
|
+
const entries = await readdir(directory, { withFileTypes: true });
|
|
16
|
+
const pages = [];
|
|
17
|
+
for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name, 'en'))) {
|
|
18
|
+
const location = path.join(directory, entry.name);
|
|
19
|
+
if (entry.isDirectory()) {
|
|
20
|
+
await addPageMetadata(location, false);
|
|
21
|
+
pages.push(entry.name);
|
|
22
|
+
continue;
|
|
23
|
+
}
|
|
24
|
+
if (!entry.name.endsWith('.md')) {
|
|
25
|
+
continue;
|
|
26
|
+
}
|
|
27
|
+
const name = entry.name.slice(0, -3);
|
|
28
|
+
const isLanding = isRoot && name === 'index';
|
|
29
|
+
const title = name === 'index' ? (isLanding ? 'API reference' : path.basename(directory)) : name;
|
|
30
|
+
const description = isLanding
|
|
31
|
+
? 'API documentation generated from the public TypeScript entry point.'
|
|
32
|
+
: `Generated API documentation for ${title}.`;
|
|
33
|
+
const body = (await readFile(location, 'utf8')).replace(/\r\n/g, '\n').trim();
|
|
34
|
+
const metadata = `---\ntitle: ${JSON.stringify(title)}\ndescription: ${JSON.stringify(description)}\n---`;
|
|
35
|
+
await writeFile(location, `${metadata}\n\n<!-- Generated by jfdevelops-docs. Do not edit directly. -->\n\n${body}\n`);
|
|
36
|
+
pages.push(name);
|
|
37
|
+
}
|
|
38
|
+
pages.sort((left, right) => (left === 'index' ? -1 : right === 'index' ? 1 : left.localeCompare(right, 'en')));
|
|
39
|
+
await writeFile(path.join(directory, 'meta.json'), `${JSON.stringify({ title: isRoot ? 'API reference' : path.basename(directory), pages }, null, 2)}\n`);
|
|
40
|
+
}
|
|
41
|
+
/** The current version of each framework gets a generated API reference. */
|
|
42
|
+
function referenceOutputs(root, config) {
|
|
43
|
+
const outputs = listVersions(root, config)
|
|
44
|
+
.frameworks.flatMap((framework) => framework.versions)
|
|
45
|
+
.map((version) => version.generatedReference)
|
|
46
|
+
.filter((output) => output !== null);
|
|
47
|
+
if (outputs.length === 0) {
|
|
48
|
+
throw new Error('No docs/framework/<framework>/v<major> directory matches the documented package major.');
|
|
49
|
+
}
|
|
50
|
+
return outputs;
|
|
51
|
+
}
|
|
52
|
+
async function convertReference(root, config, directory) {
|
|
53
|
+
const app = await Application.bootstrapWithPlugins({
|
|
54
|
+
plugin: [require.resolve('typedoc-plugin-markdown')],
|
|
55
|
+
entryPoints: [toPosix(path.join(root, config.entry))],
|
|
56
|
+
tsconfig: path.join(root, config.tsconfig),
|
|
57
|
+
outputs: [{ name: 'markdown', path: directory }],
|
|
58
|
+
readme: 'none',
|
|
59
|
+
...markdownOptions,
|
|
60
|
+
excludePrivate: true,
|
|
61
|
+
excludeProtected: true,
|
|
62
|
+
excludeInternal: true,
|
|
63
|
+
excludeExternals: true,
|
|
64
|
+
disableSources: true,
|
|
65
|
+
});
|
|
66
|
+
const project = await app.convert();
|
|
67
|
+
if (!project || app.logger.hasErrors()) {
|
|
68
|
+
throw new Error('TypeDoc conversion failed; existing reference pages were preserved.');
|
|
69
|
+
}
|
|
70
|
+
await app.generateOutputs(project);
|
|
71
|
+
if (app.logger.hasErrors()) {
|
|
72
|
+
throw new Error('TypeDoc rendering failed; existing reference pages were preserved.');
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
/**
|
|
76
|
+
* Converts the entry point once into a temporary directory, then replaces each output. Each output gets
|
|
77
|
+
* its own .gitignore, so the generated reference stays untracked without a version-specific root entry.
|
|
78
|
+
*/
|
|
79
|
+
async function generateReference(root, config, outputs) {
|
|
80
|
+
const temporary = await mkdtemp(path.join(tmpdir(), 'jfdevelops-docs-'));
|
|
81
|
+
try {
|
|
82
|
+
await convertReference(root, config, temporary);
|
|
83
|
+
await addPageMetadata(temporary);
|
|
84
|
+
await writeFile(path.join(temporary, '.gitignore'), '# Generated by jfdevelops-docs\n*\n');
|
|
85
|
+
for (const output of outputs) {
|
|
86
|
+
await rm(output, { recursive: true, force: true });
|
|
87
|
+
await cp(temporary, output, { recursive: true });
|
|
88
|
+
console.log(`Generated reference: ${toPosix(path.relative(root, output))}`);
|
|
89
|
+
}
|
|
90
|
+
}
|
|
91
|
+
finally {
|
|
92
|
+
await rm(temporary, { recursive: true, force: true });
|
|
93
|
+
}
|
|
94
|
+
}
|
|
95
|
+
/** Writes the API reference, docs/docs.json and every meta.json. */
|
|
96
|
+
export async function generateDocs({ root, config = loadConfig(root), isReferenceSkipped = false }) {
|
|
97
|
+
if (!isReferenceSkipped) {
|
|
98
|
+
await generateReference(root, config, referenceOutputs(root, config));
|
|
99
|
+
}
|
|
100
|
+
const { metaFiles } = writeDocsNavigation({ root, config });
|
|
101
|
+
console.log(`Generated navigation: docs/docs.json and ${metaFiles.size} meta.json files`);
|
|
102
|
+
}
|
package/dist/index.d.ts
ADDED
package/dist/index.js
ADDED
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
import { type DocsConfig } from './config.js';
|
|
2
|
+
/**
|
|
3
|
+
* Builds docs/docs.json and every meta.json from the docs tree. Both are generated and gitignored;
|
|
4
|
+
* page frontmatter is the source of truth.
|
|
5
|
+
*/
|
|
6
|
+
export declare const manifestSchemaVersion = 2;
|
|
7
|
+
export declare const versionId: RegExp;
|
|
8
|
+
export declare const generatedReference = "reference";
|
|
9
|
+
export type VersionStatus = 'current' | 'previous' | 'legacy' | 'next';
|
|
10
|
+
export type Frontmatter = {
|
|
11
|
+
data: Record<string, string>;
|
|
12
|
+
body: string;
|
|
13
|
+
bodyOffset: number;
|
|
14
|
+
error?: undefined;
|
|
15
|
+
} | {
|
|
16
|
+
data: null;
|
|
17
|
+
body: string;
|
|
18
|
+
error: string;
|
|
19
|
+
};
|
|
20
|
+
export type CorePackage = {
|
|
21
|
+
name: string;
|
|
22
|
+
version: string;
|
|
23
|
+
major: number;
|
|
24
|
+
repository: string | undefined;
|
|
25
|
+
};
|
|
26
|
+
export type VersionDirectory = {
|
|
27
|
+
id: string;
|
|
28
|
+
major: number;
|
|
29
|
+
status: VersionStatus;
|
|
30
|
+
path: string;
|
|
31
|
+
full: string;
|
|
32
|
+
endpointVersion: string | null;
|
|
33
|
+
generatedReference: string | null;
|
|
34
|
+
};
|
|
35
|
+
export type FrameworkDirectory = {
|
|
36
|
+
id: string;
|
|
37
|
+
title: string;
|
|
38
|
+
path: string;
|
|
39
|
+
full: string;
|
|
40
|
+
versions: VersionDirectory[];
|
|
41
|
+
};
|
|
42
|
+
export type NavigationEntry = {
|
|
43
|
+
page: string;
|
|
44
|
+
title: string;
|
|
45
|
+
} | {
|
|
46
|
+
title: string;
|
|
47
|
+
path: string;
|
|
48
|
+
pages: NavigationEntry[];
|
|
49
|
+
} | {
|
|
50
|
+
title: string;
|
|
51
|
+
path: string;
|
|
52
|
+
generated: true;
|
|
53
|
+
};
|
|
54
|
+
export type MetaFile = {
|
|
55
|
+
title?: string;
|
|
56
|
+
pages: string[];
|
|
57
|
+
};
|
|
58
|
+
export type DocsManifest = {
|
|
59
|
+
schemaVersion: number;
|
|
60
|
+
generatedBy: string;
|
|
61
|
+
library: {
|
|
62
|
+
id: string;
|
|
63
|
+
name: string;
|
|
64
|
+
npmPackage: string;
|
|
65
|
+
repository: string | undefined;
|
|
66
|
+
};
|
|
67
|
+
frameworks: Array<{
|
|
68
|
+
id: string;
|
|
69
|
+
title: string;
|
|
70
|
+
path: string;
|
|
71
|
+
defaultVersion: string | null;
|
|
72
|
+
versions: Array<{
|
|
73
|
+
id: string;
|
|
74
|
+
label: string;
|
|
75
|
+
major: number;
|
|
76
|
+
status: VersionStatus;
|
|
77
|
+
path: string;
|
|
78
|
+
package: {
|
|
79
|
+
name: string;
|
|
80
|
+
endpointVersion: string | null;
|
|
81
|
+
};
|
|
82
|
+
navigation: NavigationEntry[];
|
|
83
|
+
}>;
|
|
84
|
+
}>;
|
|
85
|
+
};
|
|
86
|
+
/** Parses the `---` frontmatter block. Values are plain scalars. */
|
|
87
|
+
export declare function parseFrontmatter(text: string): Frontmatter;
|
|
88
|
+
/** Highest released version of each major, read from the documented package's changelog. */
|
|
89
|
+
export declare function readReleasedVersions(root: string, config?: DocsConfig): Map<number, string>;
|
|
90
|
+
export declare function versionStatus(major: number, currentMajor: number): VersionStatus;
|
|
91
|
+
export declare function readCorePackage(root: string, config?: DocsConfig): CorePackage;
|
|
92
|
+
/** Lists every framework and version directory with its derived facts. */
|
|
93
|
+
export declare function listVersions(root: string, config?: DocsConfig): {
|
|
94
|
+
core: CorePackage;
|
|
95
|
+
frameworks: FrameworkDirectory[];
|
|
96
|
+
};
|
|
97
|
+
/** Builds docs.json and the meta.json files in memory. */
|
|
98
|
+
export declare function buildDocsNavigation({ root, config }: {
|
|
99
|
+
root: string;
|
|
100
|
+
config?: DocsConfig;
|
|
101
|
+
}): {
|
|
102
|
+
manifest: DocsManifest;
|
|
103
|
+
metaFiles: Map<string, MetaFile>;
|
|
104
|
+
};
|
|
105
|
+
/** Writes docs.json and every meta.json. */
|
|
106
|
+
export declare function writeDocsNavigation({ root, config }: {
|
|
107
|
+
root: string;
|
|
108
|
+
config?: DocsConfig;
|
|
109
|
+
}): {
|
|
110
|
+
manifest: DocsManifest;
|
|
111
|
+
metaFiles: Map<string, MetaFile>;
|
|
112
|
+
};
|
package/dist/manifest.js
ADDED
|
@@ -0,0 +1,214 @@
|
|
|
1
|
+
import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
|
|
2
|
+
import path from 'node:path';
|
|
3
|
+
import { loadConfig } from './config.js';
|
|
4
|
+
/**
|
|
5
|
+
* Builds docs/docs.json and every meta.json from the docs tree. Both are generated and gitignored;
|
|
6
|
+
* page frontmatter is the source of truth.
|
|
7
|
+
*/
|
|
8
|
+
export const manifestSchemaVersion = 2;
|
|
9
|
+
export const versionId = /^v(\d+)$/;
|
|
10
|
+
export const generatedReference = 'reference';
|
|
11
|
+
/** Parses the `---` frontmatter block. Values are plain scalars. */
|
|
12
|
+
export function parseFrontmatter(text) {
|
|
13
|
+
const normalized = text.replace(/\r\n/g, '\n');
|
|
14
|
+
if (!normalized.startsWith('---\n')) {
|
|
15
|
+
return { data: null, body: normalized, error: 'The page must start with a frontmatter block.' };
|
|
16
|
+
}
|
|
17
|
+
const end = normalized.indexOf('\n---', 4);
|
|
18
|
+
if (end === -1) {
|
|
19
|
+
return { data: null, body: normalized, error: 'The frontmatter block is not closed.' };
|
|
20
|
+
}
|
|
21
|
+
const data = {};
|
|
22
|
+
for (const line of normalized.slice(4, end).split('\n')) {
|
|
23
|
+
if (line.trim() === '') {
|
|
24
|
+
continue;
|
|
25
|
+
}
|
|
26
|
+
const colon = line.indexOf(':');
|
|
27
|
+
if (colon === -1) {
|
|
28
|
+
return { data: null, body: normalized, error: `Frontmatter line "${line}" is not "key: value".` };
|
|
29
|
+
}
|
|
30
|
+
const key = line.slice(0, colon).trim();
|
|
31
|
+
let value = line.slice(colon + 1).trim();
|
|
32
|
+
if (/^(".*"|'.*')$/.test(value)) {
|
|
33
|
+
value = value.slice(1, -1);
|
|
34
|
+
}
|
|
35
|
+
data[key] = value;
|
|
36
|
+
}
|
|
37
|
+
const after = normalized.indexOf('\n', end + 1);
|
|
38
|
+
const bodyOffset = after === -1 ? normalized.length : after + 1;
|
|
39
|
+
return { data, body: after === -1 ? '' : normalized.slice(after + 1), bodyOffset };
|
|
40
|
+
}
|
|
41
|
+
function toPosix(value) {
|
|
42
|
+
return value.split(path.sep).join('/');
|
|
43
|
+
}
|
|
44
|
+
function titleFromName(name) {
|
|
45
|
+
return name
|
|
46
|
+
.split('-')
|
|
47
|
+
.map((word) => word.charAt(0).toUpperCase() + word.slice(1))
|
|
48
|
+
.join(' ');
|
|
49
|
+
}
|
|
50
|
+
/** Highest released version of each major, read from the documented package's changelog. */
|
|
51
|
+
export function readReleasedVersions(root, config = loadConfig(root)) {
|
|
52
|
+
const changelog = path.join(root, config.package, 'CHANGELOG.md');
|
|
53
|
+
const latest = new Map();
|
|
54
|
+
if (!existsSync(changelog)) {
|
|
55
|
+
return new Map();
|
|
56
|
+
}
|
|
57
|
+
for (const match of readFileSync(changelog, 'utf8').matchAll(/^## (\d+)\.(\d+)\.(\d+)\s*$/gm)) {
|
|
58
|
+
const parts = match.slice(1, 4).map(Number);
|
|
59
|
+
const [major = 0, minor = 0, patch = 0] = parts;
|
|
60
|
+
const known = latest.get(major);
|
|
61
|
+
if (!known || minor > (known[1] ?? 0) || (minor === known[1] && patch > (known[2] ?? 0))) {
|
|
62
|
+
latest.set(major, parts);
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
return new Map([...latest].map(([major, parts]) => [major, parts.join('.')]));
|
|
66
|
+
}
|
|
67
|
+
export function versionStatus(major, currentMajor) {
|
|
68
|
+
if (major === currentMajor) {
|
|
69
|
+
return 'current';
|
|
70
|
+
}
|
|
71
|
+
if (major > currentMajor) {
|
|
72
|
+
return 'next';
|
|
73
|
+
}
|
|
74
|
+
return major === 0 ? 'legacy' : 'previous';
|
|
75
|
+
}
|
|
76
|
+
function readPage(full) {
|
|
77
|
+
const parsed = parseFrontmatter(readFileSync(full, 'utf8'));
|
|
78
|
+
const order = Number(parsed.data?.['order']);
|
|
79
|
+
return { title: parsed.data?.['title'] ?? null, order: Number.isInteger(order) ? order : Number.POSITIVE_INFINITY };
|
|
80
|
+
}
|
|
81
|
+
/**
|
|
82
|
+
* Walks one directory of a version. Pages come first by frontmatter `order` (then name);
|
|
83
|
+
* subdirectories follow by name.
|
|
84
|
+
*/
|
|
85
|
+
function buildDirectory(directory, base, context) {
|
|
86
|
+
const relative = toPosix(path.relative(base, directory));
|
|
87
|
+
const entries = readdirSync(directory, { withFileTypes: true });
|
|
88
|
+
const pages = entries
|
|
89
|
+
.filter((entry) => entry.isFile() && entry.name.endsWith('.md'))
|
|
90
|
+
.map((entry) => {
|
|
91
|
+
const name = entry.name.slice(0, -3);
|
|
92
|
+
const page = readPage(path.join(directory, entry.name));
|
|
93
|
+
return { name, page: relative === '' ? name : `${relative}/${name}`, title: page.title ?? titleFromName(name), order: page.order };
|
|
94
|
+
})
|
|
95
|
+
.sort((left, right) => left.order - right.order || left.name.localeCompare(right.name, 'en'));
|
|
96
|
+
const directories = entries
|
|
97
|
+
.filter((entry) => entry.isDirectory() && entry.name !== 'assets')
|
|
98
|
+
.map((entry) => entry.name)
|
|
99
|
+
.sort((left, right) => left.localeCompare(right, 'en'));
|
|
100
|
+
const navigation = pages.map(({ page, title }) => ({ page, title }));
|
|
101
|
+
for (const name of directories) {
|
|
102
|
+
const full = path.join(directory, name);
|
|
103
|
+
const title = titleFromName(name);
|
|
104
|
+
const childPath = relative === '' ? name : `${relative}/${name}`;
|
|
105
|
+
if (context.generatedReference === full) {
|
|
106
|
+
navigation.push({ title, path: childPath, generated: true });
|
|
107
|
+
}
|
|
108
|
+
else {
|
|
109
|
+
navigation.push({ title, path: childPath, pages: buildDirectory(full, base, context) });
|
|
110
|
+
}
|
|
111
|
+
}
|
|
112
|
+
if (!context.skipMeta.has(directory)) {
|
|
113
|
+
context.metaFiles.set(toPosix(path.join(directory, 'meta.json')), {
|
|
114
|
+
title: relative === '' ? context.title : titleFromName(path.basename(directory)),
|
|
115
|
+
pages: [...pages.map(({ name }) => name), ...directories],
|
|
116
|
+
});
|
|
117
|
+
}
|
|
118
|
+
return navigation;
|
|
119
|
+
}
|
|
120
|
+
export function readCorePackage(root, config = loadConfig(root)) {
|
|
121
|
+
const manifest = JSON.parse(readFileSync(path.join(root, config.package, 'package.json'), 'utf8'));
|
|
122
|
+
const repository = typeof manifest.repository === 'string' ? manifest.repository : manifest.repository?.url;
|
|
123
|
+
return {
|
|
124
|
+
name: manifest.name,
|
|
125
|
+
version: manifest.version,
|
|
126
|
+
major: Number(manifest.version.split('.')[0]),
|
|
127
|
+
repository: repository?.replace(/^git\+/, '').replace(/\.git$/, ''),
|
|
128
|
+
};
|
|
129
|
+
}
|
|
130
|
+
/** Lists every framework and version directory with its derived facts. */
|
|
131
|
+
export function listVersions(root, config = loadConfig(root)) {
|
|
132
|
+
const docsRoot = path.join(root, 'docs');
|
|
133
|
+
const frameworkRoot = path.join(docsRoot, 'framework');
|
|
134
|
+
const core = readCorePackage(root, config);
|
|
135
|
+
const released = readReleasedVersions(root, config);
|
|
136
|
+
const frameworks = [];
|
|
137
|
+
if (!existsSync(frameworkRoot)) {
|
|
138
|
+
return { core, frameworks };
|
|
139
|
+
}
|
|
140
|
+
for (const entry of readdirSync(frameworkRoot, { withFileTypes: true })) {
|
|
141
|
+
if (!entry.isDirectory()) {
|
|
142
|
+
continue;
|
|
143
|
+
}
|
|
144
|
+
const directory = path.join(frameworkRoot, entry.name);
|
|
145
|
+
const versions = readdirSync(directory, { withFileTypes: true })
|
|
146
|
+
.filter((child) => child.isDirectory() && versionId.test(child.name))
|
|
147
|
+
.map((child) => {
|
|
148
|
+
const major = Number(versionId.exec(child.name)?.[1]);
|
|
149
|
+
const full = path.join(directory, child.name);
|
|
150
|
+
const isCurrent = major === core.major;
|
|
151
|
+
return {
|
|
152
|
+
id: child.name,
|
|
153
|
+
major,
|
|
154
|
+
status: versionStatus(major, core.major),
|
|
155
|
+
path: toPosix(path.relative(docsRoot, full)),
|
|
156
|
+
full,
|
|
157
|
+
endpointVersion: isCurrent ? core.version : (released.get(major) ?? null),
|
|
158
|
+
generatedReference: isCurrent ? path.join(full, generatedReference) : null,
|
|
159
|
+
};
|
|
160
|
+
})
|
|
161
|
+
.sort((left, right) => right.major - left.major);
|
|
162
|
+
frameworks.push({ id: entry.name, title: titleFromName(entry.name), path: toPosix(path.relative(docsRoot, directory)), full: directory, versions });
|
|
163
|
+
}
|
|
164
|
+
frameworks.sort((left, right) => left.id.localeCompare(right.id, 'en'));
|
|
165
|
+
return { core, frameworks };
|
|
166
|
+
}
|
|
167
|
+
/** Builds docs.json and the meta.json files in memory. */
|
|
168
|
+
export function buildDocsNavigation({ root, config = loadConfig(root) }) {
|
|
169
|
+
const docsRoot = path.join(root, 'docs');
|
|
170
|
+
const { core, frameworks } = listVersions(root, config);
|
|
171
|
+
const metaFiles = new Map();
|
|
172
|
+
metaFiles.set(toPosix(path.join(docsRoot, 'meta.json')), { pages: ['framework'] });
|
|
173
|
+
metaFiles.set(toPosix(path.join(docsRoot, 'framework', 'meta.json')), { title: 'Frameworks', pages: frameworks.map((framework) => framework.id) });
|
|
174
|
+
const manifest = {
|
|
175
|
+
schemaVersion: manifestSchemaVersion,
|
|
176
|
+
generatedBy: 'jfdevelops-docs generate',
|
|
177
|
+
library: { id: core.name.split('/').at(-1) ?? core.name, name: config.name, npmPackage: core.name, repository: core.repository },
|
|
178
|
+
frameworks: frameworks.map((framework) => {
|
|
179
|
+
metaFiles.set(toPosix(path.join(framework.full, 'meta.json')), { title: framework.title, pages: framework.versions.map((version) => version.id) });
|
|
180
|
+
const current = framework.versions.find((version) => version.status === 'current') ?? framework.versions.find((version) => version.status !== 'next');
|
|
181
|
+
return {
|
|
182
|
+
id: framework.id,
|
|
183
|
+
title: framework.title,
|
|
184
|
+
path: framework.path,
|
|
185
|
+
defaultVersion: current?.id ?? null,
|
|
186
|
+
versions: framework.versions.map((version) => ({
|
|
187
|
+
id: version.id,
|
|
188
|
+
label: version.id,
|
|
189
|
+
major: version.major,
|
|
190
|
+
status: version.status,
|
|
191
|
+
path: version.path,
|
|
192
|
+
package: { name: core.name, endpointVersion: version.endpointVersion },
|
|
193
|
+
navigation: buildDirectory(version.full, version.full, {
|
|
194
|
+
title: version.id,
|
|
195
|
+
metaFiles,
|
|
196
|
+
generatedReference: version.generatedReference,
|
|
197
|
+
skipMeta: new Set(version.generatedReference ? [version.generatedReference] : []),
|
|
198
|
+
}),
|
|
199
|
+
})),
|
|
200
|
+
};
|
|
201
|
+
}),
|
|
202
|
+
};
|
|
203
|
+
return { manifest, metaFiles };
|
|
204
|
+
}
|
|
205
|
+
/** Writes docs.json and every meta.json. */
|
|
206
|
+
export function writeDocsNavigation({ root, config = loadConfig(root) }) {
|
|
207
|
+
const result = buildDocsNavigation({ root, config });
|
|
208
|
+
writeFileSync(path.join(root, 'docs', 'docs.json'), `${JSON.stringify(result.manifest, null, 2)}\n`);
|
|
209
|
+
for (const [file, content] of result.metaFiles) {
|
|
210
|
+
mkdirSync(path.dirname(file), { recursive: true });
|
|
211
|
+
writeFileSync(file, `${JSON.stringify(content, null, 2)}\n`);
|
|
212
|
+
}
|
|
213
|
+
return result;
|
|
214
|
+
}
|
package/package.json
CHANGED
|
@@ -1,9 +1,50 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@jfdevelops/docs",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "Generate and check versioned library docs: navigation, docs.json, and a TypeDoc API reference",
|
|
5
|
+
"type": "module",
|
|
5
6
|
"license": "MIT",
|
|
7
|
+
"repository": {
|
|
8
|
+
"type": "git",
|
|
9
|
+
"url": "git+https://github.com/jfdevelops/docs.git"
|
|
10
|
+
},
|
|
11
|
+
"bin": {
|
|
12
|
+
"jfdevelops-docs": "./dist/cli.js"
|
|
13
|
+
},
|
|
14
|
+
"exports": {
|
|
15
|
+
".": {
|
|
16
|
+
"types": "./dist/index.d.ts",
|
|
17
|
+
"default": "./dist/index.js"
|
|
18
|
+
},
|
|
19
|
+
"./package.json": "./package.json"
|
|
20
|
+
},
|
|
21
|
+
"files": [
|
|
22
|
+
"dist"
|
|
23
|
+
],
|
|
24
|
+
"engines": {
|
|
25
|
+
"node": ">=22.12.0"
|
|
26
|
+
},
|
|
27
|
+
"dependencies": {
|
|
28
|
+
"typedoc": "0.28.20",
|
|
29
|
+
"typedoc-plugin-markdown": "4.14.1",
|
|
30
|
+
"typescript": "6.0.3"
|
|
31
|
+
},
|
|
32
|
+
"devDependencies": {
|
|
33
|
+
"@changesets/cli": "^3.0.3",
|
|
34
|
+
"@types/node": "^22.20.5",
|
|
35
|
+
"vitest": "^5.0.5"
|
|
36
|
+
},
|
|
6
37
|
"publishConfig": {
|
|
7
|
-
"access": "public"
|
|
38
|
+
"access": "public",
|
|
39
|
+
"provenance": true
|
|
40
|
+
},
|
|
41
|
+
"scripts": {
|
|
42
|
+
"typecheck": "tsc",
|
|
43
|
+
"test": "vitest run",
|
|
44
|
+
"build": "node -e \"fs.rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json",
|
|
45
|
+
"check": "pnpm typecheck && pnpm test && pnpm build && pnpm pack --dry-run",
|
|
46
|
+
"changeset": "changeset",
|
|
47
|
+
"version-packages": "changeset version",
|
|
48
|
+
"release": "pnpm check && changeset publish"
|
|
8
49
|
}
|
|
9
50
|
}
|