@ankhorage/paradox 0.1.16 → 0.1.17

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (10) hide show
  1. package/CHANGELOG.md +6 -0
  2. package/README.md +7 -7
  3. package/dist/analyze/analyze.js +2 -0
  4. package/dist/analyze/types.d.ts +1 -0
  5. package/dist/config/types.d.ts +1 -0
  6. package/dist/model/buildModel.d.ts +1 -0
  7. package/dist/model/buildModel.js +1 -0
  8. package/dist/model/types.d.ts +1 -0
  9. package/dist/render/renderers/markdown.js +8 -6
  10. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,11 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.1.17
4
+
5
+ ### Patch Changes
6
+
7
+ - 8eac93d: Support section-level README Usage prose through `docs.usage.description` without requiring a source-backed usage example.
8
+
3
9
  ## 0.1.16
4
10
 
5
11
  ### Patch Changes
package/README.md CHANGED
@@ -3,7 +3,7 @@
3
3
 
4
4
  # @ankhorage/paradox
5
5
 
6
- ![license: MIT](./paradox/badges/license.svg) ![npm: v0.1.16](./paradox/badges/npm.svg) ![runtime: bun](./paradox/badges/runtime.svg) ![typescript: strict](./paradox/badges/typescript.svg) ![eslint: checked](./paradox/badges/eslint.svg) ![prettier: checked](./paradox/badges/prettier.svg) ![build: checked](./paradox/badges/build.svg) ![tests: checked](./paradox/badges/tests.svg) ![docs: paradox](./paradox/badges/docs.svg)
6
+ ![license: MIT](./paradox/badges/license.svg) ![npm: v0.1.17](./paradox/badges/npm.svg) ![runtime: bun](./paradox/badges/runtime.svg) ![typescript: strict](./paradox/badges/typescript.svg) ![eslint: checked](./paradox/badges/eslint.svg) ![prettier: checked](./paradox/badges/prettier.svg) ![build: checked](./paradox/badges/build.svg) ![tests: checked](./paradox/badges/tests.svg) ![docs: paradox](./paradox/badges/docs.svg)
7
7
 
8
8
  Deterministic documentation generator for TypeScript packages.
9
9
 
@@ -79,12 +79,12 @@ export default defineParadoxConfig({
79
79
  <details>
80
80
  <summary>Configuration options</summary>
81
81
 
82
- | Field | Type | Required | Default | Description |
83
- | ------- | --------------------------------------------------------------------------------------------- | -------- | ------- | ----------- |
84
- | mode | `'safe' \| 'write' \| undefined` | no | — | |
85
- | docs | `{ title?: string; description?: string; usage?: { entrypoints?: string[]; }; } \| undefined` | no | — | |
86
- | package | `{ root?: string; entrypoints?: string[]; } \| undefined` | no | — | |
87
- | output | `{ dir?: string; } \| undefined` | no | — | |
82
+ | Field | Type | Required | Default | Description |
83
+ | ------- | ------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ----------- |
84
+ | mode | `'safe' \| 'write' \| undefined` | no | — | |
85
+ | docs | `{ title?: string; description?: string; usage?: { description?: string; entrypoints?: string[]; }; } \| undefined` | no | — | |
86
+ | package | `{ root?: string; entrypoints?: string[]; } \| undefined` | no | — | |
87
+ | output | `{ dir?: string; } \| undefined` | no | — | |
88
88
 
89
89
  </details>
90
90
 
package/dist/analyze/analyze.js CHANGED
@@ -22,6 +22,7 @@ export async function analyze(config, runtime) {
22
22
  const badges = await analyzeBadges(root, pkg);
23
23
  const project = createProject(root);
24
24
  const entrypoints = config.package?.entrypoints ?? ['src/index.ts'];
25
+ const readmeUsageDescription = config.docs?.usage?.description ?? null;
25
26
  const usageEntryPoints = config.docs?.usage?.entrypoints ?? [];
26
27
  const readmeUsage = await analyzeReadmeUsage({ root, entrypoints: usageEntryPoints });
27
28
  const program = createTypeScriptProgram({ root, entrypoints, project });
@@ -67,6 +68,7 @@ export async function analyze(config, runtime) {
67
68
  badges,
68
69
  sequenceScenarios,
69
70
  usage,
71
+ readmeUsageDescription,
70
72
  readmeUsage,
71
73
  config: configMetadata
72
74
  ? {
package/dist/analyze/types.d.ts CHANGED
@@ -163,6 +163,7 @@ export interface AnalysisResult {
163
163
  badges: AnalysisBadge[];
164
164
  sequenceScenarios: AnalysisSequenceScenario[];
165
165
  usage: AnalysisUsage | null;
166
+ readmeUsageDescription: string | null;
166
167
  readmeUsage: AnalysisReadmeUsage[];
167
168
  config: {
168
169
  exportName: string;
package/dist/config/types.d.ts CHANGED
@@ -10,6 +10,7 @@ export interface ParadoxConfig {
10
10
  title?: string;
11
11
  description?: string;
12
12
  usage?: {
13
+ description?: string;
13
14
  entrypoints?: string[];
14
15
  };
15
16
  };
package/dist/model/buildModel.d.ts CHANGED
@@ -107,6 +107,7 @@ interface BuildModelInput {
107
107
  command: string;
108
108
  }[];
109
109
  } | null;
110
+ readmeUsageDescription: string | null;
110
111
  readmeUsage: {
111
112
  title: string | null;
112
113
  description: string | null;
package/dist/model/buildModel.js CHANGED
@@ -24,6 +24,7 @@ export function buildModel(analysis) {
24
24
  }))),
25
25
  }
26
26
  : null,
27
+ readmeUsageDescription: analysis.readmeUsageDescription,
27
28
  readmeUsage: analysis.readmeUsage
28
29
  .map((usageEntry) => ({
29
30
  title: usageEntry.title,
package/dist/model/types.d.ts CHANGED
@@ -7,6 +7,7 @@ export interface DocumentationModel {
7
7
  description: string | null;
8
8
  badges: GeneratedBadge[];
9
9
  usage: UsageModel | null;
10
+ readmeUsageDescription: string | null;
10
11
  readmeUsage: ReadmeUsageModel[];
11
12
  config: ConfigModel | null;
12
13
  entrypoints: string[];
package/dist/render/renderers/markdown.js CHANGED
@@ -23,7 +23,7 @@ function renderReadme(model, outputDir, badges, diagrams) {
23
23
  }
24
24
  if (model.description)
25
25
  lines.push(model.description, '');
26
- renderReadmeUsage(lines, model.readmeUsage);
26
+ renderReadmeUsage(lines, model.readmeUsageDescription, model.readmeUsage);
27
27
  if (model.usage !== null) {
28
28
  lines.push('## Installation', '', '```bash');
29
29
  for (const command of model.usage.commands)
@@ -37,18 +37,20 @@ function renderReadme(model, outputDir, badges, diagrams) {
37
37
  renderReadmeApi(lines, model);
38
38
  return `${lines.join('\n').trimEnd()}\n`;
39
39
  }
40
- function renderReadmeUsage(lines, entries) {
41
- if (entries.length === 0)
40
+ function renderReadmeUsage(lines, description, entries) {
41
+ if (description === null && entries.length === 0)
42
42
  return;
43
43
  lines.push('## Usage', '');
44
+ if (description !== null)
45
+ lines.push(description, '');
44
46
  for (const entry of entries) {
45
47
  if (entry.title !== null)
46
48
  lines.push(`### ${entry.title}`, '');
47
49
  if (entry.description !== null) {
48
50
  const [, ...rest] = entry.description.split('\n');
49
- const description = rest.join('\n').trim();
50
- if (description.length > 0)
51
- lines.push(description, '');
51
+ const entryDescription = rest.join('\n').trim();
52
+ if (entryDescription.length > 0)
53
+ lines.push(entryDescription, '');
52
54
  }
53
55
  lines.push(`Source: \`${entry.sourcePath}\``, '');
54
56
  lines.push(`\`\`\`${entry.language}`);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ankhorage/paradox",
3
- "version": "0.1.16",
3
+ "version": "0.1.17",
4
4
  "description": "Deterministic documentation generator for TypeScript packages.",
5
5
  "license": "MIT",
6
6
  "publishConfig": {