typedoc 0.23.5 → 0.23.6

package/dist/lib/converter/converter.js

@@ -20,6 +20,8 @@ const symbols_1 = require("./symbols");
 const paths_1 = require("../utils/paths");
 const enum_1 = require("../utils/enum");
 const comments_1 = require("./comments");
+const parser_1 = require("./comments/parser");
+const rawLexer_1 = require("./comments/rawLexer");
 /**
  * Compiles source files using TypeScript and converts compiler symbols to reflections.
  */
@@ -73,7 +75,7 @@ let Converter = Converter_1 = class Converter extends component_1.ChildableCompo
         });
         entries.forEach((e) => {
             context.setActiveProgram(e.entryPoint.program);
-            e.context = this.convertExports(context, e.entryPoint.sourceFile, entries.length === 1, e.entryPoint.displayName);
+            e.context = this.convertExports(context, e.entryPoint, entries.length === 1);
         });
         for (const { entryPoint, context } of entries) {
             // active program is already set on context
@@ -84,7 +86,9 @@ let Converter = Converter_1 = class Converter extends component_1.ChildableCompo
         }
         context.setActiveProgram(undefined);
     }
-    convertExports(context, node, singleEntryPoint, entryName) {
+    convertExports(context, entryPoint, singleEntryPoint) {
+        const node = entryPoint.sourceFile;
+        const entryName = entryPoint.displayName;
         const symbol = getSymbolForModuleLike(context, node);
         let moduleContext;
         const allExports = getExports(context, node, symbol);
@@ -104,6 +108,19 @@ let Converter = Converter_1 = class Converter extends component_1.ChildableCompo
         }
         else {
             const reflection = context.createDeclarationReflection(index_1.ReflectionKind.Module, symbol, void 0, entryName);
+            if (entryPoint.readmeFile) {
+                const readme = (0, utils_1.readFile)(entryPoint.readmeFile);
+                const comment = (0, parser_1.parseComment)((0, rawLexer_1.lexCommentString)(readme), context.converter.config, new utils_1.MinimalSourceFile(readme, entryPoint.readmeFile), context.logger);
+                if (comment.blockTags.length || comment.modifierTags.size) {
+                    const ignored = [
+                        ...comment.blockTags.map((tag) => tag.tag),
+                        ...comment.modifierTags,
+                    ];
+                    context.logger.warn(`Block and modifier tags will be ignored within the readme:\n\t${ignored.join("\n\t")}`);
+                }
+                reflection.readme = comment.summary;
+            }
+            reflection.version = entryPoint.version;
             context.finalizeDeclarationReflection(reflection);
             moduleContext = context.withScope(reflection);
         }

package/dist/lib/converter/plugins/LinkResolverPlugin.js

@@ -14,8 +14,9 @@ const declarationReference_1 = require("../comments/declarationReference");
 const ts = require("typescript");
 const utils_1 = require("../../utils");
 const declarationReferenceResolver_1 = require("../comments/declarationReferenceResolver");
+const models_1 = require("../../models");
 const urlPrefix = /^(http|ftp)s?:\/\//;
-const brackets = /\[\[([^\]]+)\]\]/g;
+const brackets = /\[\[(?!include:)([^\]]+)\]\]/g;
 /**
  * A plugin that resolves `{@link Foo}` tags.
  */
@@ -113,6 +114,9 @@ let LinkResolverPlugin = LinkResolverPlugin_1 = class LinkResolverPlugin extends
         for (const tag of comment.blockTags) {
             tag.content = this.processParts(reflection, tag.content, warn);
         }
+        if (reflection instanceof models_1.DeclarationReflection && reflection.readme) {
+            reflection.readme = this.processParts(reflection, reflection.readme, warn);
+        }
     }
     processParts(reflection, parts, warn) {
         return parts.flatMap((part) => this.processPart(reflection, part, warn));

package/dist/lib/converter/plugins/PackagePlugin.d.ts

@@ -1,4 +1,5 @@
 import { ConverterComponent } from "../components";
+import { EntryPointStrategy } from "../../utils";
 /**
  * A handler that tries to find the package.json and readme.md files of the
  * current project.
@@ -6,6 +7,7 @@ import { ConverterComponent } from "../components";
 export declare class PackagePlugin extends ConverterComponent {
     readme: string;
     includeVersion: boolean;
+    entryPointStrategy: EntryPointStrategy;
     /**
      * The file name of the found readme.md file.
      */

package/dist/lib/converter/plugins/PackagePlugin.js

@@ -102,7 +102,11 @@ let PackagePlugin = class PackagePlugin extends components_1.ConverterComponent
                     project.name = `${project.name} - v${packageInfo.version}`;
                 }
                 else {
-                    context.logger.warn("--includeVersion was specified, but package.json does not specify a version.");
+                    // since not all monorepo specifies a meaningful version to the main package.json
+                    // this warning should be optional
+                    if (this.entryPointStrategy !== utils_1.EntryPointStrategy.Packages) {
+                        context.logger.warn("--includeVersion was specified, but package.json does not specify a version.");
+                    }
                 }
             }
         }
@@ -112,7 +116,11 @@ let PackagePlugin = class PackagePlugin extends components_1.ConverterComponent
                 project.name = "Documentation";
             }
             if (this.includeVersion) {
-                context.logger.warn("--includeVersion was specified, but no package.json was found. Not adding package version to the documentation.");
+                // since not all monorepo specifies a meaningful version to the main package.json
+                // this warning should be optional
+                if (this.entryPointStrategy !== utils_1.EntryPointStrategy.Packages) {
+                    context.logger.warn("--includeVersion was specified, but no package.json was found. Not adding package version to the documentation.");
+                }
             }
         }
     }
@@ -123,6 +131,9 @@ __decorate([
 __decorate([
     (0, utils_1.BindOption)("includeVersion")
 ], PackagePlugin.prototype, "includeVersion", void 0);
+__decorate([
+    (0, utils_1.BindOption)("entryPointStrategy")
+], PackagePlugin.prototype, "entryPointStrategy", void 0);
 PackagePlugin = __decorate([
     (0, components_1.Component)({ name: "package" })
 ], PackagePlugin);

package/dist/lib/models/reflections/declaration.d.ts

@@ -5,6 +5,7 @@ import { ContainerReflection } from "./container";
 import type { SignatureReflection } from "./signature";
 import type { TypeParameterReflection } from "./type-parameter";
 import type { Serializer, JSONOutput } from "../../serialization";
+import type { CommentDisplayPart } from "../comments";
 /**
  * Stores hierarchical type data.
  *
@@ -109,6 +110,14 @@ export declare class DeclarationReflection extends ContainerReflection {
      * rendered in templates.
      */
     typeHierarchy?: DeclarationHierarchy;
+    /**
+     * The contents of the readme file of the module when found.
+     */
+    readme?: CommentDisplayPart[];
+    /**
+     * The version of the module when found.
+     */
+    version?: string;
     hasGetterOrSetter(): boolean;
     getAllSignatures(): SignatureReflection[];
     /** @internal */

package/dist/lib/output/themes/default/DefaultThemeRenderContext.d.ts

@@ -39,6 +39,9 @@ export declare class DefaultThemeRenderContext {
     members: (props: import("../../../models").ContainerReflection) => import("../../../utils/jsx.elements").JsxElement;
     membersGroup: (group: import("../../../models").ReflectionGroup) => import("../../../utils/jsx.elements").JsxElement;
     navigation: (props: import("../..").PageEvent<Reflection>) => import("../../../utils/jsx.elements").JsxElement;
+    settings: () => import("../../../utils/jsx.elements").JsxElement;
+    primaryNavigation: (props: import("../..").PageEvent<Reflection>) => import("../../../utils/jsx.elements").JsxElement;
+    secondaryNavigation: (props: import("../..").PageEvent<Reflection>) => import("../../../utils/jsx.elements").JsxElement | undefined;
     parameter: (props: import("../../../models").DeclarationReflection) => import("../../../utils/jsx.elements").JsxElement;
     toolbar: (props: import("../..").PageEvent<Reflection>) => import("../../../utils/jsx.elements").JsxElement;
     type: (type: import("../../../models").Type | undefined) => import("../../../utils/jsx.elements").JsxElement;

package/dist/lib/output/themes/default/DefaultThemeRenderContext.js

@@ -68,6 +68,9 @@ class DefaultThemeRenderContext {
         this.members = bind(members_1.members, this);
         this.membersGroup = bind(members_group_1.membersGroup, this);
         this.navigation = bind(navigation_1.navigation, this);
+        this.settings = bind(navigation_1.settings, this);
+        this.primaryNavigation = bind(navigation_1.primaryNavigation, this);
+        this.secondaryNavigation = bind(navigation_1.secondaryNavigation, this);
         this.parameter = bind(parameter_1.parameter, this);
         this.toolbar = bind(toolbar_1.toolbar, this);
         this.type = bind(type_1.type, this);

package/dist/lib/output/themes/default/partials/header.d.ts

@@ -1,5 +1,5 @@
 import { JSX } from "../../../../utils";
 import type { DefaultThemeRenderContext } from "../DefaultThemeRenderContext";
 import type { PageEvent } from "../../../events";
-import type { Reflection } from "../../../../models";
+import { Reflection } from "../../../../models";
 export declare const header: (context: DefaultThemeRenderContext, props: PageEvent<Reflection>) => JSX.Element;

package/dist/lib/output/themes/default/partials/header.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.header = void 0;
 const lib_1 = require("../../lib");
 const utils_1 = require("../../../../utils");
+const models_1 = require("../../../../models");
 const header = (context, props) => {
     const HeadingLevel = props.model.isProject() ? "h2" : "h1";
     return (utils_1.JSX.createElement("div", { class: "tsd-page-title" },
@@ -10,6 +11,9 @@ const header = (context, props) => {
         utils_1.JSX.createElement(HeadingLevel, null,
             props.model.kindString !== "Project" && `${props.model.kindString ?? ""} `,
             props.model.name,
+            props.model instanceof models_1.DeclarationReflection &&
+                props.model.version !== undefined &&
+                ` - v${props.model.version}`,
             (0, lib_1.hasTypeParameters)(props.model) && (utils_1.JSX.createElement(utils_1.JSX.Fragment, null,
                 "<",
                 (0, lib_1.join)(", ", props.model.typeParameters, (item) => item.name),

package/dist/lib/output/themes/default/partials/index.d.ts

@@ -1,4 +1,4 @@
 import type { DefaultThemeRenderContext } from "../DefaultThemeRenderContext";
 import { JSX } from "../../../../utils";
-import type { ContainerReflection } from "../../../../models";
+import { ContainerReflection } from "../../../../models";
 export declare function index(context: DefaultThemeRenderContext, props: ContainerReflection): JSX.Element;

package/dist/lib/output/themes/default/partials/index.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.index = void 0;
 const lib_1 = require("../../lib");
 const utils_1 = require("../../../../utils");
+const models_1 = require("../../../../models");
 function renderCategory({ urlTo, icons }, item, prependName = "") {
     return (utils_1.JSX.createElement("section", { class: "tsd-index-section" },
         utils_1.JSX.createElement("h3", { class: "tsd-index-heading" }, prependName ? `${prependName} - ${item.title}` : item.title),
@@ -36,7 +37,13 @@ function index(context, props) {
             utils_1.JSX.createElement("h3", { class: "tsd-index-heading uppercase" }, "Index"),
             content));
     }
-    return (utils_1.JSX.createElement("section", { class: "tsd-panel-group tsd-index-group" },
-        utils_1.JSX.createElement("section", { class: "tsd-panel tsd-index-panel" }, content)));
+    return (utils_1.JSX.createElement(utils_1.JSX.Fragment, null,
+        props instanceof models_1.DeclarationReflection &&
+            props.kind === models_1.ReflectionKind.Module &&
+            props.readme?.length !== 0 && (utils_1.JSX.createElement("section", { class: "tsd-panel-group" },
+            utils_1.JSX.createElement("section", { class: "tsd-panel tsd-typography" },
+                utils_1.JSX.createElement(utils_1.Raw, { html: context.markdown((0, lib_1.displayPartsToMarkdown)(props.readme || [], context.urlTo)) })))),
+        utils_1.JSX.createElement("section", { class: "tsd-panel-group tsd-index-group" },
+            utils_1.JSX.createElement("section", { class: "tsd-panel tsd-index-panel" }, content))));
 }
 exports.index = index;

package/dist/lib/output/themes/default/partials/navigation.d.ts

@@ -3,3 +3,6 @@ import { JSX } from "../../../../utils";
 import type { PageEvent } from "../../../events";
 import type { DefaultThemeRenderContext } from "../DefaultThemeRenderContext";
 export declare function navigation(context: DefaultThemeRenderContext, props: PageEvent<Reflection>): JSX.Element;
+export declare function settings(context: DefaultThemeRenderContext): JSX.Element;
+export declare function primaryNavigation(context: DefaultThemeRenderContext, props: PageEvent<Reflection>): JSX.Element;
+export declare function secondaryNavigation(context: DefaultThemeRenderContext, props: PageEvent<Reflection>): JSX.Element | undefined;

package/dist/lib/output/themes/default/partials/navigation.js

@@ -1,14 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.navigation = void 0;
+exports.secondaryNavigation = exports.primaryNavigation = exports.settings = exports.navigation = void 0;
 const models_1 = require("../../../../models");
 const utils_1 = require("../../../../utils");
 const lib_1 = require("../../lib");
 function navigation(context, props) {
     return (utils_1.JSX.createElement(utils_1.JSX.Fragment, null,
-        settings(context),
-        primaryNavigation(context, props),
-        secondaryNavigation(context, props)));
+        context.settings(),
+        context.primaryNavigation(props),
+        context.secondaryNavigation(props)));
 }
 exports.navigation = navigation;
 function buildFilterItem(context, name, displayName, defaultValue) {
@@ -55,6 +55,7 @@ function settings(context) {
                         utils_1.JSX.createElement("option", { value: "light" }, "Light"),
                         utils_1.JSX.createElement("option", { value: "dark" }, "Dark")))))));
 }
+exports.settings = settings;
 function primaryNavigation(context, props) {
     // Create the navigation for the current page
     const modules = props.model.project.getChildrenByKind(models_1.ReflectionKind.SomeModule);
@@ -82,10 +83,11 @@ function primaryNavigation(context, props) {
             childNav = utils_1.JSX.createElement("ul", null, childModules.map(link));
         }
         return (utils_1.JSX.createElement("li", { class: (0, lib_1.classNames)({ current, selected, deprecated: mod.isDeprecated() }, mod.cssClasses) },
-            utils_1.JSX.createElement("a", { href: context.urlTo(mod) }, (0, lib_1.wbr)(mod.name)),
+            utils_1.JSX.createElement("a", { href: context.urlTo(mod) }, (0, lib_1.wbr)(`${mod.name}${mod.version !== undefined ? ` - v${mod.version}` : ""}`)),
             childNav));
     }
 }
+exports.primaryNavigation = primaryNavigation;
 function secondaryNavigation(context, props) {
     // Multiple entry points, and on main project page.
     if (props.model.isProject() && props.model.getChildrenByKind(models_1.ReflectionKind.Module).length) {
@@ -117,6 +119,7 @@ function secondaryNavigation(context, props) {
                     utils_1.JSX.createElement("span", null, (0, lib_1.wbr)(effectivePageParent.name))),
                 !!pageNavigation.length && utils_1.JSX.createElement("ul", null, pageNavigation)))));
 }
+exports.secondaryNavigation = secondaryNavigation;
 function inPath(thisPage, toCheck) {
     while (toCheck) {
         if (toCheck.isProject())

package/dist/lib/utils/entry-point.d.ts

@@ -25,8 +25,10 @@ export declare const EntryPointStrategy: {
 export declare type EntryPointStrategy = typeof EntryPointStrategy[keyof typeof EntryPointStrategy];
 export interface DocumentationEntryPoint {
     displayName: string;
+    readmeFile?: string;
     program: ts.Program;
     sourceFile: ts.SourceFile;
+    version?: string;
 }
 export declare function getEntryPoints(logger: Logger, options: Options): DocumentationEntryPoint[] | undefined;
 export declare function getWatchEntryPoints(logger: Logger, options: Options, program: ts.Program): DocumentationEntryPoint[] | undefined;

package/dist/lib/utils/entry-point.js

@@ -4,6 +4,7 @@ exports.getExpandedEntryPointsForPaths = exports.getWatchEntryPoints = exports.g
 const path_1 = require("path");
 const ts = require("typescript");
 const FS = require("fs");
+const Path = require("path");
 const package_manifest_1 = require("./package-manifest");
 const paths_1 = require("./paths");
 const fs_1 = require("./fs");
@@ -205,6 +206,10 @@ function getEntryPointsForPackages(logger, packageGlobPaths, options) {
     for (const packagePath of expandedPackages) {
         const packageJsonPath = (0, path_1.resolve)(packagePath, "package.json");
         const packageJson = (0, package_manifest_1.loadPackageManifest)(logger, packageJsonPath);
+        const includeVersion = options.getValue("includeVersion");
+        const typedocPackageConfig = packageJson
+            ? (0, package_manifest_1.extractTypedocConfigFromPackageManifest)(logger, packageJsonPath)
+            : undefined;
         if (packageJson === undefined) {
             logger.error(`Could not load package manifest ${packageJsonPath}`);
             return;
@@ -248,8 +253,18 @@ function getEntryPointsForPackages(logger, packageGlobPaths, options) {
             logger.error(`Entry point "${packageEntryPoint}" does not appear to be built by the tsconfig found at "${tsconfigFile}"`);
             return;
         }
+        if (includeVersion &&
+            (!packageJson["version"] ||
+                typeof packageJson["version"] !== "string")) {
+            logger.warn(`--includeVersion was specified, but "${(0, paths_1.nicePath)(packageJsonPath)}" does not properly specify a version.`);
+        }
         results.push({
-            displayName: packageJson["name"],
+            displayName: typedocPackageConfig?.displayName ??
+                packageJson["name"],
+            version: packageJson["version"],
+            readmeFile: typedocPackageConfig?.readmeFile
+                ? Path.resolve(Path.join(packageJsonPath, "..", typedocPackageConfig?.readmeFile))
+                : undefined,
             program,
             sourceFile,
         });

package/dist/lib/utils/loggers.js

@@ -98,16 +98,18 @@ class Logger {
         this.log(text, LogLevel.Info);
     }
     warn(text, ...args) {
-        if (this.seenWarnings.has(text))
+        const text2 = this.addContext(text, LogLevel.Warn, ...args);
+        if (this.seenWarnings.has(text2))
             return;
-        this.seenWarnings.add(text);
-        this.log(this.addContext(text, LogLevel.Warn, ...args), LogLevel.Warn);
+        this.seenWarnings.add(text2);
+        this.log(text2, LogLevel.Warn);
     }
     error(text, ...args) {
-        if (this.seenErrors.has(text))
+        const text2 = this.addContext(text, LogLevel.Error, ...args);
+        if (this.seenErrors.has(text2))
             return;
-        this.seenErrors.add(text);
-        this.log(this.addContext(text, LogLevel.Error, ...args), LogLevel.Error);
+        this.seenErrors.add(text2);
+        this.log(text2, LogLevel.Error);
     }
     /** @internal */
     deprecated(text, addStack = true) {

package/dist/lib/utils/package-manifest.d.ts

@@ -1,9 +1,21 @@
 import type { Logger } from "./loggers";
 import type { IMinimatch } from "minimatch";
+import { additionalProperties, Infer } from "./validation";
 /**
  * Loads a package.json and validates that it is a JSON Object
  */
 export declare function loadPackageManifest(logger: Logger, packageJsonPath: string): Record<string, unknown> | undefined;
+declare const typedocPackageManifestConfigSchema: {
+    displayName: import("./validation").Optional<StringConstructor>;
+    entryPoint: import("./validation").Optional<StringConstructor>;
+    readmeFile: import("./validation").Optional<StringConstructor>;
+    [additionalProperties]: boolean;
+};
+export declare type TypedocPackageManifestConfig = Infer<typeof typedocPackageManifestConfigSchema>;
+/**
+ * Extracts typedoc specific config from a specified package manifest
+ */
+export declare function extractTypedocConfigFromPackageManifest(logger: Logger, packageJsonPath: string): TypedocPackageManifestConfig | undefined;
 /**
  * Given a list of (potentially wildcarded) package paths,
  * return all the actual package folders found.
@@ -20,3 +32,4 @@ export declare const ignorePackage: unique symbol;
  *   the necessary metadata for us to document.
  */
 export declare function getTsEntryPointForPackage(logger: Logger, packageJsonPath: string, packageJson: Record<string, unknown>): string | undefined | typeof ignorePackage;
+export {};

package/dist/lib/utils/package-manifest.js

@@ -1,11 +1,12 @@
 "use strict";
 // Utilities to support the inspection of node package "manifests"
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getTsEntryPointForPackage = exports.ignorePackage = exports.expandPackages = exports.loadPackageManifest = void 0;
+exports.getTsEntryPointForPackage = exports.ignorePackage = exports.expandPackages = exports.extractTypedocConfigFromPackageManifest = exports.loadPackageManifest = void 0;
 const path_1 = require("path");
 const fs_1 = require("fs");
 const fs_2 = require("./fs");
 const paths_1 = require("./paths");
+const validation_1 = require("./validation");
 /**
  * Helper for the TS type system to understand hasOwnProperty
  * and narrow a type appropriately.
@@ -27,6 +28,32 @@ function loadPackageManifest(logger, packageJsonPath) {
     return packageJson;
 }
 exports.loadPackageManifest = loadPackageManifest;
+const typedocPackageManifestConfigSchema = {
+    displayName: (0, validation_1.optional)(String),
+    entryPoint: (0, validation_1.optional)(String),
+    readmeFile: (0, validation_1.optional)(String),
+    [validation_1.additionalProperties]: false,
+};
+/**
+ * Extracts typedoc specific config from a specified package manifest
+ */
+function extractTypedocConfigFromPackageManifest(logger, packageJsonPath) {
+    const packageJson = loadPackageManifest(logger, packageJsonPath);
+    if (!packageJson) {
+        return undefined;
+    }
+    if (hasOwnProperty(packageJson, "typedoc") &&
+        typeof packageJson.typedoc == "object" &&
+        packageJson.typedoc) {
+        if (!(0, validation_1.validate)(typedocPackageManifestConfigSchema, packageJson.typedoc)) {
+            logger.error(`Typedoc config extracted from package manifest file ${packageJsonPath} is not valid`);
+            return undefined;
+        }
+        return packageJson.typedoc;
+    }
+    return undefined;
+}
+exports.extractTypedocConfigFromPackageManifest = extractTypedocConfigFromPackageManifest;
 /**
  * Load the paths to packages specified in a Yarn workspace package JSON
  * Returns undefined if packageJSON does not define a Yarn workspace
@@ -146,8 +173,13 @@ exports.ignorePackage = Symbol("ignorePackage");
 function getTsEntryPointForPackage(logger, packageJsonPath, packageJson) {
     let packageMain = "index.js"; // The default, per the npm docs.
     let packageTypes = null;
-    if (hasOwnProperty(packageJson, "typedocMain") &&
+    const typedocPackageConfig = extractTypedocConfigFromPackageManifest(logger, packageJsonPath);
+    if (typedocPackageConfig?.entryPoint) {
+        packageMain = typedocPackageConfig.entryPoint;
+    }
+    else if (hasOwnProperty(packageJson, "typedocMain") &&
         typeof packageJson.typedocMain == "string") {
+        logger.warn(`Legacy typedoc entry point config (using "typedocMain" field) found for "${(0, paths_1.nicePath)(packageJsonPath)}". Please update to use "typedoc": { "entryPoint": "..." } instead. In future upgrade, "typedocMain" field will be ignored.`);
         packageMain = packageJson.typedocMain;
     }
     else if (hasOwnProperty(packageJson, "main") &&

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "typedoc",
   "description": "Create api documentation for TypeScript projects.",
-  "version": "0.23.5",
+  "version": "0.23.6",
   "homepage": "https://typedoc.org",
   "main": "./dist/index.js",
   "exports": {