Skip to content

Commit c317a99

Browse files
tgreyuktgreyuk
committed
chore(core): expose dedicated async jobs to renderer
1 parent c8939fc commit c317a99

File tree

11 files changed

+147
-134
lines changed

11 files changed

+147
-134
lines changed

‎packages/typedoc-plugin-markdown/src/index.ts

+14-58
Original file line numberDiff line numberDiff line change
@@ -3,20 +3,16 @@
33
*
44
* @module core
55
*/
6-
import { getTranslatable } from '@plugin/internationalization/translatable.js';
6+
import { setupInternationalization } from '@plugin/internationalization/index.js';
77
import { declarations } from '@plugin/options/index.js';
8-
import { resolvePackages } from '@plugin/renderer/packages.js';
9-
import { MarkdownRendererHooks, MarkdownTheme } from 'public-api.js';
8+
import { render, setupRenderer } from '@plugin/renderer/index.js';
9+
import { MarkdownRenderer } from '@plugin/types/index.js';
1010
import {
1111
Application,
12-
Context,
13-
Converter,
1412
DeclarationOption,
15-
EventHooks,
1613
ParameterHint,
1714
ParameterType,
1815
} from 'typedoc';
19-
import { render } from './renderer/render.js';
2016

2117
/**
2218
* The function that is called by TypeDoc to bootstrap the plugin.
@@ -27,13 +23,6 @@ import { render } from './renderer/render.js';
2723
*
2824
* This method is not intended to be consumed in any other context that via the `plugin` option.
2925
*
30-
* The load functions:
31-
*
32-
* 1. Bootstrap the plugin options
33-
* 2. Configures markdown outputs
34-
* 3. Configures localization
35-
* 4. Applies any other behaviour
36-
*
3726
* The module also exports anything that is available publicly.
3827
*
3928
*/
@@ -43,22 +32,13 @@ export function load(app: Application) {
4332
* 1. Bootstrap options
4433
* ====================
4534
*/
46-
47-
// Iterate over declaration definitions and to the container.
4835
Object.entries(declarations).forEach(([name, declaration]) => {
4936
app.options.addDeclaration({
5037
name,
5138
...declaration,
5239
} as DeclarationOption);
5340
});
5441

55-
app.renderer.defineTheme('markdown', MarkdownTheme);
56-
57-
/**
58-
* =============================
59-
* 2. Configure markdown outputs
60-
* =============================
61-
*/
6242
app.options.addDeclaration({
6343
name: 'markdown',
6444
outputShortcut: 'markdown',
@@ -68,48 +48,24 @@ export function load(app: Application) {
6848
defaultValue: './docs',
6949
});
7050

71-
app.outputs.addOutput('markdown', async (out, project) => {
72-
await render(app.renderer, project, out);
73-
});
74-
75-
app.outputs.setDefaultOutputName('markdown');
76-
77-
Object.defineProperty(app.renderer, 'markdownHooks', {
78-
value: new EventHooks<MarkdownRendererHooks, string>(),
79-
});
80-
8151
/**
82-
* =========================
83-
* 3. Configure localization
84-
* =========================
52+
* =============================
53+
* 2. Configure markdown outputs
54+
* =============================
8555
*/
86-
87-
// Load the additional translations used by the theme for the selected language.
88-
app.converter.on(Converter.EVENT_BEGIN, () => {
89-
app.internationalization.addTranslations(
90-
app.options.getValue('lang'),
91-
{ ...getTranslatable(app) },
92-
true,
93-
);
56+
app.outputs.addOutput('markdown', async (out, project) => {
57+
await render(app.renderer as unknown as MarkdownRenderer, project, out);
9458
});
9559

96-
/**
97-
* ============================
98-
* 4. Apply any other behaviour
99-
* ============================
100-
*/
60+
app.outputs.setDefaultOutputName('markdown');
10161

10262
/**
103-
* Currently options set for packages are only stored on the converter and are destroyed before being passed to the {@link Renderer}.
104-
*
105-
* By intercepting the package options set in the converter and storing them on the renderer we can use them later in the theme.
106-
*
63+
* =====================================
64+
* 3. Setup up renderer and translations
65+
* ======================================
10766
*/
108-
app.converter.on(Converter.EVENT_RESOLVE_END, (context: Context) => {
109-
if (app.options.packageDir) {
110-
resolvePackages(app, context, app.options.packageDir);
111-
}
112-
});
67+
setupRenderer(app);
68+
setupInternationalization(app);
11369
}
11470

11571
/**

‎packages/typedoc-plugin-markdown/src/internationalization/index.ts

+1-1
Original file line numberDiff line numberDiff line change
@@ -8,4 +8,4 @@
88
* @module
99
*/
1010
export * from './locales/index.js';
11-
export * from './translatable.js';
11+
export * from './setup.js';

‎packages/typedoc-plugin-markdown/src/internationalization/setup.ts

+35
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
import { en, jp, ko, zh } from '@plugin/internationalization/index.js';
2+
import { Application, Converter } from 'typedoc';
3+
4+
export function setupInternationalization(app: Application): void {
5+
app.converter.on(Converter.EVENT_BEGIN, () => {
6+
app.internationalization.addTranslations(
7+
app.options.getValue('lang'),
8+
{ ...getTranslatable(app) },
9+
true,
10+
);
11+
});
12+
}
13+
14+
/**
15+
* Returns subset of translatable strings for the plugin.
16+
*
17+
* These will then be merged with the main set of TypeDoc string.
18+
*
19+
* @category Functions
20+
*/
21+
function getTranslatable(app: Application) {
22+
const LOCALES = {
23+
en,
24+
jp,
25+
ko,
26+
zh,
27+
};
28+
return {
29+
...LOCALES['en'],
30+
...(app.lang !== 'en' && Object.keys(LOCALES).includes(app.lang)
31+
? { ...LOCALES[app.lang] }
32+
: {}),
33+
...app.options.getValue('locales')[app.lang],
34+
};
35+
}

‎packages/typedoc-plugin-markdown/src/internationalization/translatable.ts

-25
Original file line numberDiff line numberDiff line change
@@ -3,28 +3,3 @@
33
*
44
* @module
55
*/
6-
import { en, jp, ko, zh } from 'internationalization/index.js';
7-
import { Application } from 'typedoc';
8-
9-
/**
10-
* Returns subset of translatable strings for the plugin.
11-
*
12-
* These will then be merged with the main set of TypeDoc string.
13-
*
14-
* @category Functions
15-
*/
16-
export function getTranslatable(app: Application) {
17-
const LOCALES = {
18-
en,
19-
jp,
20-
ko,
21-
zh,
22-
};
23-
return {
24-
...LOCALES['en'],
25-
...(app.lang !== 'en' && Object.keys(LOCALES).includes(app.lang)
26-
? { ...LOCALES[app.lang] }
27-
: {}),
28-
...app.options.getValue('locales')[app.lang],
29-
};
30-
}

‎packages/typedoc-plugin-markdown/src/renderer/index.ts

+1-1
Original file line numberDiff line numberDiff line change
@@ -4,5 +4,5 @@
44
* @module
55
*/
66

7-
export * from './packages.js';
87
export * from './render.js';
8+
export * from './setup.js';

‎packages/typedoc-plugin-markdown/src/renderer/packages.ts

-37
This file was deleted.

‎packages/typedoc-plugin-markdown/src/renderer/render.ts

+7-4
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,8 @@ import {
22
MarkdownPageEvent,
33
MarkdownRendererEvent,
44
} from '@plugin/events/index.js';
5-
import { MarkdownTheme } from '@plugin/public-api.js';
5+
import { MarkdownTheme } from '@plugin/theme/index.js';
6+
import { MarkdownRenderer } from '@plugin/types/index.js';
67
import * as fs from 'fs';
78
import * as path from 'path';
89
import {
@@ -24,7 +25,7 @@ import {
2425
* - Adds any logic specific to markdown rendering.
2526
*/
2627
export async function render(
27-
renderer: Renderer,
28+
renderer: MarkdownRenderer,
2829
project: ProjectReflection,
2930
outputDirectory: string,
3031
) {
@@ -49,13 +50,15 @@ export async function render(
4950

5051
renderer.trigger(MarkdownRendererEvent.BEGIN, output);
5152

52-
await executeJobs(renderer.preRenderAsyncJobs, output);
53+
await executeJobs(renderer.preMarkdownRenderAsyncJobs, output);
54+
await executeJobs(renderer.preRenderAsyncJobs, output); // for backward compatibility
5355

5456
await renderPages(renderer, output);
5557

5658
copyMediaFiles(project, outputDirectory);
5759

58-
await executeJobs(renderer.postRenderAsyncJobs, output);
60+
await executeJobs(renderer.postMarkdownRenderAsyncJobs, output);
61+
await executeJobs(renderer.postRenderAsyncJobs, output); // for backward compatibility
5962

6063
renderer.trigger(MarkdownRendererEvent.END, output);
6164

‎packages/typedoc-plugin-markdown/src/renderer/setup.ts

+66
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
import { MarkdownTheme } from '@plugin/theme/index.js';
2+
import {
3+
MarkdownRenderer,
4+
MarkdownRendererHooks,
5+
} from '@plugin/types/index.js';
6+
import * as fs from 'fs';
7+
import * as path from 'path';
8+
import { Application, Context, Converter, EventHooks } from 'typedoc';
9+
10+
/**
11+
* Create dedicated hooks and async job collections for markdown rendering.
12+
*/
13+
export function setupRenderer(app: Application) {
14+
app.renderer.defineTheme('markdown', MarkdownTheme);
15+
16+
Object.defineProperty(app.renderer, 'markdownHooks', {
17+
value: new EventHooks<MarkdownRendererHooks, string>(),
18+
});
19+
20+
Object.defineProperty(app.renderer, 'preMarkdownRenderAsyncJobs', {
21+
value: [],
22+
});
23+
24+
Object.defineProperty(app.renderer, 'postMarkdownRenderAsyncJobs', {
25+
value: [],
26+
});
27+
28+
app.converter.on(Converter.EVENT_RESOLVE_END, (context: Context) => {
29+
if (app.options.packageDir) {
30+
resolvePackages(app, context, app.options.packageDir);
31+
}
32+
});
33+
}
34+
35+
/**
36+
* Resolves packages meta data for the project.
37+
*
38+
* @remarks
39+
*
40+
* Currently options set for packages are only stored on the converter and are destroyed before being passed to the Renderer.
41+
*
42+
* By intercepting the package options set in the converter and storing them on the renderer we can use them later in the theme.
43+
*/
44+
function resolvePackages(
45+
app: Application,
46+
context: Context,
47+
packageDir: string,
48+
) {
49+
const packageJsonContents = fs
50+
.readFileSync(path.join(packageDir, 'package.json'))
51+
.toString();
52+
53+
const packageJson = packageJsonContents
54+
? JSON.parse(packageJsonContents)
55+
: {};
56+
57+
const renderer = app.renderer as unknown as MarkdownRenderer;
58+
59+
renderer.packagesMeta = {
60+
...(renderer.packagesMeta || {}),
61+
[context.project.name]: {
62+
description: packageJson.description,
63+
options: app.options,
64+
},
65+
};
66+
}

‎packages/typedoc-plugin-markdown/src/theme/markdown-theme.ts

-5
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,6 @@ import {
1010
ProjectReflection,
1111
Reflection,
1212
ReflectionKind,
13-
Renderer,
1413
Theme,
1514
} from 'typedoc';
1615

@@ -24,10 +23,6 @@ import {
2423
* The API follows the implementation of [TypeDoc's custom theming](https://github.com/TypeStrong/typedoc/blob/master/internal-docs/custom-themes.md) with some minor adjustments.
2524
*/
2625
export class MarkdownTheme extends Theme {
27-
constructor(renderer: Renderer) {
28-
super(renderer);
29-
}
30-
3126
/**
3227
* Renders a template and page model to a string.
3328
*/

0 commit comments

Comments
 (0)