Skip to content

Commit

Permalink
chore(docs): updated documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@tgreyuk
tgreyuk committed Jun 8, 2024
1 parent 277ea72 commit 3b5d608
Show file tree
Hide file tree
Showing 56 changed files with 1,582 additions and 1,564 deletions.
7 changes: 7 additions & 0 deletions devtools/packages/helpers/constants.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,13 @@ export const DOCS_CONFIG: Record<string, DocsConfig> = {
docsPath: '/docs',
declarations: true,
presets: false,
categories: {
file: 'Options that are used to configure how files are output.',
display:
'Options that are used to configure how the output is structured and displayed .',
utility:
'Options that are used for general configuration and utility purposes.',
},
},
['typedoc-plugin-frontmatter']: {
declarationsPath: `${process.cwd()}/src/options/declarations.ts`,
Expand Down
1 change: 1 addition & 0 deletions devtools/packages/helpers/models.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ export interface DocsConfig {
docsPath: string;
declarations: boolean;
presets: boolean;
categories?: Record<string, string>;
}

export interface OptionDocument {
Expand Down
131 changes: 94 additions & 37 deletions devtools/packages/prebuild-options/tasks/generate-docs.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,40 +10,40 @@ export async function generateOptionsDocs(docsConfig: DocsConfig) {
tsConfigFilePath: 'tsconfig.json',
});

// PRESETS
const out: string[] = [
const outputPage: string[] = [
`import { Callout, FileTree } from 'nextra/components';`,
];

out.push('# Options');
outputPage.push('# Options');
if (docsConfig.docsPath === '/docs') {
out.push(
`These options should be used in conjunction with core TypeDoc options (see [TypeDoc Usage](/docs/typedoc-usage)).`,
outputPage.push(
`<Callout type="info">These options should be used in conjunction with the core TypeDoc options (see [TypeDoc Usage](/docs/typedoc-usage)).</Callout>`,
);
} else {
if (docsConfig.presets) {
out.push(
outputPage.push(
`<Callout type="info">Please view options exposed by [typedoc-plugin-markdown](/docs/options) in addition to those listed here.</Callout>`,
);
}
}

if (docsConfig.presets) {
out.push('## Preset Options');
out.push('The following are preset typedoc-plugin-markdown options:');
outputPage.push('## Preset Options');
outputPage.push(
'The following are preset typedoc-plugin-markdown options:',
);
const presetsConfig: any = await import(docsConfig.presetsPath as string);
const config = presetsConfig.default;
delete config.plugin;
const presetsJson = JSON.stringify(config, null, 2);

out.push(`\`\`\`json"
outputPage.push(`\`\`\`json"
${presetsJson}
\`\`\``);
out.push('## Plugin Options');
out.push('The following options are exposed by this plugin:');
outputPage.push('## Plugin Options');
outputPage.push('The following options are exposed by this plugin:');
}

// DECLARATIONS
if (docsConfig.declarations) {
const declarationsConfig: any = await import(
docsConfig.declarationsPath as string
Expand All @@ -55,8 +55,8 @@ ${presetsJson}
const optionsVariableStatements =
configFileTs?.getVariableStatements() as VariableStatement[];

const parsedConfig = Object.entries(declarationsConfig).map(
([name, option]: any, i) => {
const parsedConfig = Object.entries(declarationsConfig)
.map(([name, option]: any, i) => {
const docs = optionsVariableStatements[i].getJsDocs().map((doc) => {
return {
comments: (doc.getComment() as string)
Expand All @@ -75,6 +75,9 @@ ${presetsJson}
name: tag.getTagName(),
comments: tag.getComment(),
})),
hidden: Boolean(
doc.getTags().find((tag) => tag.getTagName() === 'hidden'),
),
omitExample: Boolean(
doc.getTags().find((tag) => tag.getTagName() === 'omitExample'),
),
Expand All @@ -98,8 +101,8 @@ ${presetsJson}
...option,
...(docs ? docs : { category: 'other' }),
};
},
);
})
.filter((option) => !option.hidden);

const groupedConfig: Record<string, any> = groupBy(
parsedConfig,
Expand All @@ -108,27 +111,47 @@ ${presetsJson}

const categories = Object.entries(groupedConfig);

categories.forEach(([categoryName, options]) => {
categories.forEach(async ([categoryName, options]) => {
const out: string[] = [
categories.length > 1
? `import { Callout, FileTree } from 'nextra/components';`
: '',
];
const optionLevel =
categories.length === 1 && !Boolean(docsConfig.presets) ? '##' : '###';
categories.length === 1 && !Boolean(docsConfig.presets) ? '##' : '##';
if (categories.length > 1) {
out.push(`## ${getDocsTitle(categoryName)}`);
out.push(`# ${getDocsTitle(categoryName)}`);
outputPage.push(`## ${getDocsTitle(categoryName)}`);
if (docsConfig.categories) {
outputPage.push(docsConfig.categories[categoryName.toLowerCase()]);
}
}
const optionsLi: string[] = [];
options.forEach((option) => {
optionsLi.push(
`- [${
Boolean(option.deprecated)
? `~--${option.name}~`
: `--${option.name}`
}](./options/${categoryName.toLowerCase()}-options.mdx#--${option.name.toLowerCase()})`,
);
out.push(
`${optionLevel} ${
Boolean(option.deprecated) ? `~${option.name}~` : `${option.name}`
Boolean(option.deprecated)
? `~--${option.name}~`
: `--${option.name}`
}`,
);
if (Boolean(option.deprecated)) {
out.push(
`<Callout type="warning">Deprecated - ${option.deprecated}</Callout>`,
`<Callout type="warning">Deprecated: ${option.deprecated}</Callout>`,
);
} else {
out.push(
`<Callout emoji="${getEmoji(categoryName)}">${option.help}</Callout>`,
);
}

const meta: string[] = [];
const type = getType(option);
if (type) {
Expand Down Expand Up @@ -160,34 +183,68 @@ ${presetsJson}
) {
//out.push('Below is the full list of keys and default values:');
}

out.push(`
}
out.push(`
\`\`\`json filename="typedoc.json"
${JSON.stringify(
JSON.parse(`{
"${option.name}": ${getExampleValue(option)}
}`),
"${option.name}": ${getExampleValue(option)}
}`),
null,
2,
)}
\`\`\``);
}
out.push('___');
});
if (categories.length > 1) {
outputPage.push(optionsLi.join('\n'));
const catDocPath = path.join(
getPagesPath(docsConfig.optionsPath),
'options',
`${categoryName.toLowerCase()}-options.mdx`,
);
const formattedOut = await prettier.format(out.join('\n\n'), {
parser: 'mdx',
});
fs.writeFileSync(catDocPath, formattedOut);
} else {
outputPage.push(out.join('\n\n'));
}
});
}
if (categories.length > 1) {
const metaJs = await prettier.format(
`export default ${JSON.stringify(
categories.reduce((prev, curr) => {
return {
...prev,
[`${curr[0].toLowerCase()}-options`]: '',
};
}, {}),
)}`,
{
parser: 'typescript',
},
);

const optionDocPath = path.join(
getPagesPath(docsConfig.optionsPath),
'options.mdx',
);
const metaJsPath = path.join(
getPagesPath(docsConfig.optionsPath),
'options',
'_meta.js',
);

const formattedOut = await prettier.format(out.join('\n\n'), {
parser: 'mdx',
});
fs.writeFileSync(metaJsPath, metaJs);
}

const optionDocPath = path.join(
getPagesPath(docsConfig.optionsPath),
'options.mdx',
);

fs.writeFileSync(optionDocPath, formattedOut);
const formattedOut = await prettier.format(outputPage.join('\n\n'), {
parser: 'mdx',
});

fs.writeFileSync(optionDocPath, formattedOut);
}
}

function getEmoji(categoryName: string) {
Expand Down
8 changes: 4 additions & 4 deletions devtools/packages/prebuild-options/tasks/generate-models.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -193,12 +193,12 @@ function getType(
.join(';')}}`;
}
if (option.type === ParameterType.Mixed && option.defaultValue) {
const usePartial = name === 'textContentMappings';
const useAny = name === 'textContentMappings';
return isInterface
? usePartial
? `Partial<${capitalize(name)}>`
? useAny
? `Partial<any>`
: capitalize(name)
: usePartial
: useAny
? `ManuallyValidatedOption<Partial<${capitalize(name)}>>`
: `ManuallyValidatedOption<${capitalize(name)}>`;
}
Expand Down
3 changes: 2 additions & 1 deletion docs/global.css
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,8 @@
.nextra-toc a[href^='#parameters-'],
.nextra-toc a[href^='#returns'],
.nextra-toc a[href^='#source'],
.nextra-toc a[href^='#overrides'] {
.nextra-toc a[href^='#overrides'],
.nextra-toc a[href^='#deprecated'] {
display: none;
}
blockquote {
Expand Down
4 changes: 2 additions & 2 deletions docs/pages/api-docs/Class.MarkdownPageEvent.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,13 +14,13 @@ export function load(app: MarkdownApplication) {

## Extends

- [`Event ↗️`]( https://typedoc.org/api/classes/Event.html )
- [`Event`](https://typedoc.org/api/classes/Event.html)

## Properties

### project

> **project**: [`ProjectReflection ↗️`]( https://typedoc.org/api/classes/Models.ProjectReflection.html )
> **project**: [`ProjectReflection`](https://typedoc.org/api/classes/Models.ProjectReflection.html)
The project the renderer is currently processing.

Expand Down
6 changes: 3 additions & 3 deletions docs/pages/api-docs/Class.MarkdownRendererEvent.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,13 +12,13 @@ app.renderer.on(MarkdownRendererEvent.BEGIN, (event) => {

## Extends

- [`Event ↗️`]( https://typedoc.org/api/classes/Event.html )
- [`Event`](https://typedoc.org/api/classes/Event.html)

## Properties

### project

> `readonly` **project**: [`ProjectReflection ↗️`]( https://typedoc.org/api/classes/Models.ProjectReflection.html )
> `readonly` **project**: [`ProjectReflection`](https://typedoc.org/api/classes/Models.ProjectReflection.html)
The project the renderer is currently processing.

Expand All @@ -34,7 +34,7 @@ The path of the directory the documentation should be written to.

### urls?

> `optional` **urls**: [`UrlMapping`](/api-docs/Interface.UrlMapping.md)\<[`Reflection ↗️`]( https://typedoc.org/api/classes/Models.Reflection.html )\>[]
> `optional` **urls**: [`UrlMapping`](/api-docs/Interface.UrlMapping.md)\<[`Reflection`](https://typedoc.org/api/classes/Models.Reflection.html)\>[]
A list of all pages that should be generated.

Expand Down
12 changes: 6 additions & 6 deletions docs/pages/api-docs/Class.MarkdownTheme.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ class MyMarkdownTheme extends MarkdownTheme {

## Extends

- [`Theme ↗️`]( https://typedoc.org/api/classes/Theme.html )
- [`Theme`](https://typedoc.org/api/classes/Theme.html)

## Methods

Expand All @@ -38,7 +38,7 @@ This method can be overridden to provide an alternative theme context.

| Parameter | Type |
| :------ | :------ |
| `page` | [`MarkdownPageEvent`](/api-docs/Class.MarkdownPageEvent.md)\<[`Reflection ↗️`]( https://typedoc.org/api/classes/Models.Reflection.html )\> |
| `page` | [`MarkdownPageEvent`](/api-docs/Class.MarkdownPageEvent.md)\<[`Reflection`](https://typedoc.org/api/classes/Models.Reflection.html)\> |

#### Returns

Expand All @@ -48,7 +48,7 @@ This method can be overridden to provide an alternative theme context.

### getUrls()

> **getUrls**(`project`): [`UrlMapping`](/api-docs/Interface.UrlMapping.md)\<[`Reflection ↗️`]( https://typedoc.org/api/classes/Models.Reflection.html )\>[]
> **getUrls**(`project`): [`UrlMapping`](/api-docs/Interface.UrlMapping.md)\<[`Reflection`](https://typedoc.org/api/classes/Models.Reflection.html)\>[]
Maps the models of the given project to the desired output files.

Expand All @@ -58,11 +58,11 @@ This method can be overriden to provide an alternative url structure.

| Parameter | Type |
| :------ | :------ |
| `project` | [`ProjectReflection ↗️`]( https://typedoc.org/api/classes/Models.ProjectReflection.html ) |
| `project` | [`ProjectReflection`](https://typedoc.org/api/classes/Models.ProjectReflection.html) |

#### Returns

[`UrlMapping`](/api-docs/Interface.UrlMapping.md)\<[`Reflection ↗️`]( https://typedoc.org/api/classes/Models.Reflection.html )\>[]
[`UrlMapping`](/api-docs/Interface.UrlMapping.md)\<[`Reflection`](https://typedoc.org/api/classes/Models.Reflection.html)\>[]

#### Overrides

Expand All @@ -82,7 +82,7 @@ This method can be overriden to provide an alternative navigation structure.

| Parameter | Type |
| :------ | :------ |
| `project` | [`ProjectReflection ↗️`]( https://typedoc.org/api/classes/Models.ProjectReflection.html ) |
| `project` | [`ProjectReflection`](https://typedoc.org/api/classes/Models.ProjectReflection.html) |

#### Returns

Expand Down
Loading

0 comments on commit 3b5d608

Please sign in to comment.