diff --git a/site/options.md b/site/options.md index 584ec0b30..3a8413cc4 100644 --- a/site/options.md +++ b/site/options.md @@ -13,148 +13,43 @@ children: Any command line arguments that are passed without a flag will be parsed as entry points. Any options passed on the command line will override options set in a configuration file. - - ## Configuration Options Options which control what files TypeDoc reads. -- [options](options/configuration.md#options) -- [tsconfig](options/configuration.md#tsconfig) -- [compilerOptions](options/configuration.md#compileroptions) -- [plugin](options/configuration.md#plugin) +{@listOptions options/configuration.md} ## Input Options Options which control how input is converted into a project that can be rendered to HTML or JSON. -- [entryPoints](options/input.md#entrypoints) -- [entryPointStrategy](options/input.md#entrypointstrategy) -- [packageOptions](options/input.md#packageoptions) -- [alwaysCreateEntryPointModule](options/input.md#alwayscreateentrypointmodule) -- [projectDocuments](options/input.md#projectdocuments) -- [exclude](options/input.md#exclude) -- [externalPattern](options/input.md#externalpattern) -- [excludeExternals](options/input.md#excludeexternals) -- [excludeNotDocumented](options/input.md#excludenotdocumented) -- [excludeNotDocumentedKinds](options/input.md#excludenotdocumentedkinds) -- [excludeInternal](options/input.md#excludeinternal) -- [excludePrivate](options/input.md#excludeprivate) -- [excludeProtected](options/input.md#excludeprotected) -- [excludeReferences](options/input.md#excludereferences) -- [excludeCategories](options/input.md#excludecategories) -- [maxTypeConversionDepth](options/input.md#maxtypeconversiondepth) -- [name](options/input.md#name) -- [includeVersion](options/input.md#includeversion) -- [disableSources](options/input.md#disablesources) -- [sourceLinkTemplate](options/input.md#sourcelinktemplate) -- [gitRevision](options/input.md#gitrevision) -- [gitRemote](options/input.md#gitremote) -- [disableGit](options/input.md#disablegit) -- [readme](options/input.md#readme) -- [includeHierarchySummary](options/input.md#includehierarchysummary) +{@listOptions options/input.md} ## Output Options Options which control TypeDoc's HTML output. -- [outputs](options/output.md#outputs) -- [out](options/output.md#out) -- [html](options/output.md#html) -- [json](options/output.md#json) -- [pretty](options/output.md#pretty) -- [emit](options/output.md#emit) -- [theme](options/output.md#theme) -- [lightHighlightTheme](options/output.md#lighthighlighttheme) -- [darkHighlightTheme](options/output.md#darkhighlighttheme) -- [highlightLanguages](options/output.md#highlightlanguages) -- [typePrintWidth](options/output.md#typeprintwidth) -- [customCss](options/output.md#customcss) -- [customJs](options/output.md#customjs) -- [customFooterHtml](options/output.md#customfooterhtml) -- [customFooterHtmlDisableWrapper](options/output.md#customfooterhtmldisablewrapper) -- [markdownItOptions](options/output.md#markdownitoptions) -- [markdownItLoader](options/output.md#markdownitloader) -- [basePath](options/output.md#basepath) -- [cname](options/output.md#cname) -- [favicon](options/output.md#favicon) -- [sourceLinkExternal](options/output.md#sourcelinkexternal) -- [markdownLinkExternal](options/output.md#markdownlinkexternal) -- [lang](options/output.md#lang) -- [locales](options/output.md#locales) -- [githubPages](options/output.md#githubpages) -- [cacheBust](options/output.md#cachebust) -- [hideGenerator](options/output.md#hidegenerator) -- [searchInComments](options/output.md#searchincomments) -- [searchInDocuments](options/output.md#searchindocuments) -- [cleanOutputDir](options/output.md#cleanoutputdir) -- [titleLink](options/output.md#titlelink) -- [navigationLinks](options/output.md#navigationlinks) -- [sidebarLinks](options/output.md#sidebarlinks) -- [navigation](options/output.md#navigation) -- [headings](options/output.md#headings) -- [sluggerConfiguration](options/output.md#sluggerconfiguration) -- [navigationLeaves](options/output.md#navigationleaves) -- [visibilityFilters](options/output.md#visibilityfilters) -- [searchCategoryBoosts](options/output.md#searchcategoryboosts) -- [searchGroupBoosts](options/output.md#searchgroupboosts) -- [hostedBaseUrl](options/output.md#hostedbaseurl) -- [useHostedBaseUrlForAbsoluteLinks](options/output.md#usehostedbaseurlforabsolutelinks) -- [useFirstParagraphOfCommentAsSummary](options/output.md#usefirstparagraphofcommentassummary) +{@listOptions options/output.md} ## Comment Options Options which control how TypeDoc parses comments. -- [commentStyle](options/comments.md#commentstyle) -- [useTsLinkResolution](options/comments.md#usetslinkresolution) -- [preserveLinkText](options/comments.md#preservelinktext) -- [jsDocCompatibility](options/comments.md#jsdoccompatibility) -- [suppressCommentWarningsInDeclarationFiles](options/comments.md#suppresscommentwarningsindeclarationfiles) -- [blockTags](options/comments.md#blocktags) -- [inlineTags](options/comments.md#inlinetags) -- [modifierTags](options/comments.md#modifiertags) -- [cascadedModifierTags](options/comments.md#cascadedmodifiertags) -- [excludeTags](options/comments.md#excludetags) -- [notRenderedTags](options/comments.md#notrenderedtags) -- [externalSymbolLinkMappings](options/comments.md#externalsymbollinkmappings) +{@listOptions options/comments.md} ## Organization Options Controls how TypeDoc organizes content within a converted project. -- [groupReferencesByType](options/organization.md#groupreferencesbytype) -- [categorizeByGroup](options/organization.md#categorizebygroup) -- [defaultCategory](options/organization.md#defaultcategory) -- [categoryOrder](options/organization.md#categoryorder) -- [groupOrder](options/organization.md#grouporder) -- [sort](options/organization.md#sort) -- [sortEntryPoints](options/organization.md#sortentrypoints) -- [kindSortOrder](options/organization.md#kindsortorder) +{@listOptions options/organization.md} ## Validation Options Configures the validation performed by TypeDoc on a converted project. -- [validation](options/validation.md#validation) -- [treatWarningsAsErrors](options/validation.md#treatwarningsaserrors) -- [treatValidationWarningsAsErrors](options/validation.md#treatvalidationwarningsaserrors) -- [intentionallyNotExported](options/validation.md#intentionallynotexported) -- [requiredToBeDocumented](options/validation.md#requiredtobedocumented) +{@listOptions options/validation.md} ## Other Options -- [watch](options/other.md#watch) -- [preserveWatchOutput](options/other.md#preservewatchoutput) -- [help](options/other.md#help) -- [version](options/other.md#version) -- [showConfig](options/other.md#showconfig) -- [logLevel](options/other.md#loglevel) -- [skipErrorChecking](options/other.md#skiperrorchecking) +{@listOptions options/other.md} diff --git a/site/site-plugin.js b/site/site-plugin.js new file mode 100644 index 000000000..006e98e97 --- /dev/null +++ b/site/site-plugin.js @@ -0,0 +1,89 @@ +// @ts-check +import { readFileSync } from "node:fs"; +import { dirname, join } from "node:path"; +import { Application, Converter, OptionDefaults } from "typedoc"; +/** @import { CommentDisplayPart, FileRegistry, TranslatedString} from "typedoc" */ + +/** @param {Application} app */ +export function load(app) { + app.on(Application.EVENT_BOOTSTRAP_END, () => { + app.options.setValue("inlineTags", [ + ...OptionDefaults.inlineTags, + "@listOptions", + ]); + }); + + app.converter.on(Converter.EVENT_CREATE_DOCUMENT, (_ctx, doc) => { + // Known we have this as documents always have a file path + const fileName = /** @type {string} */ ( + doc.project.files.getReflectionPath(doc) + ); + + replaceListOptions(fileName, doc.content, doc.project.files); + }); + + /** + * + * @param {string} sourceFile + * @param {CommentDisplayPart[]} parts + * @param {FileRegistry} files + */ + function replaceListOptions(sourceFile, parts, files) { + for (let i = 0; i < parts.length; ++i) { + const part = parts[i]; + if (part.kind === "inline-tag" && part.tag === "@listOptions") { + parts.splice( + i, + 1, + ...buildListOptions(sourceFile, part.text.trim(), files), + ); + } + } + } + + /** + * @param {string} sourceFile + * @param {string} userPath + * @param {FileRegistry} files + * @returns {CommentDisplayPart[]} + */ + function buildListOptions(sourceFile, userPath, files) { + const file = join(dirname(sourceFile), userPath.trim()); + + /** @type {string[]} */ + const headings = []; + const content = readFileSync(file, "utf-8"); + for (const line of content.split("\n")) { + if (line.startsWith("## ")) { + headings.push(line.substring(3).trim()); + } + } + + /** @type {CommentDisplayPart[]} */ + const result = []; + + for (const heading of headings) { + result.push({ kind: "text", text: `- [${heading}](` }); + const text = userPath + "#" + heading.toLowerCase(); + const relPath = files.register(sourceFile, text); + if (!relPath) { + app.logger.warn( + /** @type {TranslatedString} */ ( + `@listOptions specified a file "${text}" which does not exist` + ), + ); + return []; + } + + result.push({ + kind: "relative-link", + target: relPath?.target, + targetAnchor: relPath?.anchor, + text, + }); + result.push({ kind: "text", text: ")\n" }); + } + + return result; + } +} diff --git a/site/typedoc.config.jsonc b/site/typedoc.config.jsonc index 0a30ee2c2..192364a1a 100644 --- a/site/typedoc.config.jsonc +++ b/site/typedoc.config.jsonc @@ -7,7 +7,7 @@ "alwaysCreateEntryPointModule": true, "out": "../docs-site", "name": "TypeDoc", - "plugin": ["./typedoc-plugin-redirect.js"], + "plugin": ["./typedoc-plugin-redirect.js", "./site-plugin.js"], "readme": "index.md", "projectDocuments": [ diff --git a/src/lib/converter/converter.ts b/src/lib/converter/converter.ts index 2c32276c1..8d56499b6 100644 --- a/src/lib/converter/converter.ts +++ b/src/lib/converter/converter.ts @@ -191,6 +191,14 @@ export class Converter extends AbstractComponent { static readonly EVENT_CREATE_DECLARATION = ConverterEvents.CREATE_DECLARATION; + /** + * Triggered when the converter has created a document reflection. + * The listener will be given `undefined` (for consistency with the + * other create events) and a {@link Models.DocumentReflection}. + * @event + */ + static readonly EVENT_CREATE_DOCUMENT = ConverterEvents.CREATE_DOCUMENT; + /** * Triggered when the converter has created a signature reflection. * The listener will be given {@link Context}, {@link Models.SignatureReflection} | {@link Models.ProjectReflection} the declaration,