Repository navigation
Expand file tree
/
Copy pathtypedoc.scripts.config.mjs
More file actions
151 lines (145 loc) · 4.48 KB
/
Copy pathtypedoc.scripts.config.mjs
File metadata and controls
151 lines (145 loc) · 4.48 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
/* eslint-disable-next-line import/no-unresolved */
import { OptionDefaults } from 'typedoc';
/**
* TypeDoc configuration for the reusable scripts in scripts/esm, published at
* https://api.playcanvas.com/scripts/. Run via `npm run docs:scripts` (requires the engine
* types to be built first, which the npm script takes care of).
*/
const ENGINE_DOCS = 'https://api.playcanvas.com/engine';
// Script attribute tags (parsed by the Editor's attribute parser). Registered so TypeDoc
// accepts them; all but @description are UI metadata and are excluded from the output.
const ATTRIBUTE_TAGS = [
'@attribute',
'@title',
'@description',
'@range',
'@precision',
'@step',
'@visibleif',
'@enabledif',
'@resource'
];
/**
* Engine symbols referenced by the scripts' JSDoc (including comments inherited from base
* classes like Script and EventHandler via the d.ts), grouped by the page type they have in the
* engine API reference. TypeDoc warns about any referenced symbol missing from these lists
* ("...resolved but is not included in the documentation") — harvest such warnings into the
* matching list.
*/
const engineSymbols = {
classes: [
'AppBase',
'Asset',
'BoundingBox',
'CameraComponent',
'CameraFrame',
'Color',
'ContainerResource',
'Entity',
'EventHandle',
'EventHandler',
'GraphicsDevice',
'GSplatContainer',
'GSplatFormat',
'Layer',
'Material',
'Mesh',
'MeshInstance',
'Quat',
'RenderTarget',
'Scene',
'Script',
'ScriptComponent',
'Shader',
'ShaderMaterial',
'StandardMaterial',
'Texture',
'Vec2',
'Vec3',
'VertexBuffer',
'XrInputSource'
],
interfaces: [],
types: [
'HandleEventCallback'
],
variables: [],
functions: [],
// Class.member references, mapped to lowercased anchors on the class page
members: [
'EventHandle.off',
'Scene.ambientLight'
]
};
const playcanvasLinks = {};
for (const [group, dir] of [
['classes', 'classes'],
['interfaces', 'interfaces'],
['types', 'types'],
['variables', 'variables'],
['functions', 'functions']
]) {
for (const name of engineSymbols[group]) {
playcanvasLinks[name] = `${ENGINE_DOCS}/${dir}/${name}.html`;
}
}
for (const ref of engineSymbols.members) {
const [cls, member] = ref.split('.');
playcanvasLinks[ref] = `${ENGINE_DOCS}/classes/${cls}.html#${member.toLowerCase()}`;
}
export default {
blockTags: [...OptionDefaults.blockTags, ...ATTRIBUTE_TAGS],
// Categories sort alphabetically, with the catch-all pinned last
categoryOrder: ['*', 'Supporting Types'],
// @category is not supported on @typedef comments, so the state/resources typedefs (and
// anything untagged) fall back to this category
defaultCategory: 'Supporting Types',
compilerOptions: {
allowSyntheticDefaultImports: true,
checkJs: false
},
excludeTags: [...OptionDefaults.excludeTags, ...ATTRIBUTE_TAGS.filter(t => t !== '@description')],
entryPoints: [
'./scripts/esm'
],
entryPointStrategy: 'expand',
exclude: [
'**/node_modules/**',
// resource-handler parsers, not scripts
'**/scripts/esm/parsers/**'
],
excludeNotDocumented: true,
externalSymbolLinkMappings: {
playcanvas: playcanvasLinks
},
favicon: 'utils/typedoc/favicon.ico',
hostedBaseUrl: 'https://api.playcanvas.com/scripts/',
includeVersion: true,
// Most scripts export a single class, so collapse the per-file modules into one flat
// project (classes listed directly, like the engine reference)
mergeModulesMergeMode: 'project',
name: 'Engine Scripts API Reference',
// Group the sidebar by the @category tags on the script classes
navigation: {
includeCategories: true
},
navigationLinks: {
'Developer Site': 'https://developer.playcanvas.com/',
'Blog': 'https://blog.playcanvas.com/',
'Discord': 'https://discord.gg/RSaMRzg',
'Forum': 'https://forum.playcanvas.com/',
'GitHub': 'https://github.com/playcanvas/engine'
},
out: 'docs-scripts',
plugin: [
'typedoc-plugin-mdn-links',
'typedoc-plugin-merge-modules'
],
readme: 'scripts/esm/README.md',
sidebarLinks: {
'Home': '/'
},
searchGroupBoosts: {
'Classes': 2
}
};