typedoc - npm Package Compare versions

Comparing version 0.23.5 to 0.23.6

dist/lib/converter/converter.js

@@ -23,2 +23,4 @@ "use strict";
 const comments_1 = require("./comments");
+const parser_1 = require("./comments/parser");
+const rawLexer_1 = require("./comments/rawLexer");
 /**
@@ -77,3 +79,3 @@ * Compiles source files using TypeScript and converts compiler symbols to reflections.
             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);
         });
@@ -89,3 +91,5 @@ for (const { entryPoint, context } of entries) {
     }
-    convertExports(context, node, singleEntryPoint, entryName) {
+    convertExports(context, entryPoint, singleEntryPoint) {
+        const node = entryPoint.sourceFile;
+        const entryName = entryPoint.displayName;
         const symbol = getSymbolForModuleLike(context, node);
@@ -110,2 +114,15 @@ let moduleContext;
             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);
@@ -112,0 +129,0 @@ moduleContext = context.withScope(reflection);

dist/lib/converter/plugins/LinkResolverPlugin.js

@@ -17,4 +17,5 @@ "use strict";
 const declarationReferenceResolver_1 = require("../comments/declarationReferenceResolver");
+const models_1 = require("../../models");
 const urlPrefix = /^(http|ftp)s?:\/\//;
-const brackets = /\[\[([^\]]+)\]\]/g;
+const brackets = /\[\[(?!include:)([^\]]+)\]\]/g;
 /**
@@ -117,2 +118,5 @@ * A plugin that resolves `{@link Foo}` tags.
         }
+        if (reflection instanceof models_1.DeclarationReflection && reflection.readme) {
+            reflection.readme = this.processParts(reflection, reflection.readme, warn);
+        }
     }
@@ -119,0 +123,0 @@ processParts(reflection, parts, warn) {

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

 import { ConverterComponent } from "../components";
+import { EntryPointStrategy } from "../../utils";
 /**
@@ -9,2 +10,3 @@ * A handler that tries to find the package.json and readme.md files of the
     includeVersion: boolean;
+    entryPointStrategy: EntryPointStrategy;
     /**
@@ -11,0 +13,0 @@ * The file name of the found readme.md file.

dist/lib/converter/plugins/PackagePlugin.js

@@ -105,3 +105,7 @@ "use strict";
                 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.");
+                    }
                 }
@@ -116,3 +120,7 @@ }
             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.");
+                }
             }
@@ -128,2 +136,5 @@ }
 ], PackagePlugin.prototype, "includeVersion", void 0);
+__decorate([
+    (0, utils_1.BindOption)("entryPointStrategy")
+], PackagePlugin.prototype, "entryPointStrategy", void 0);
 PackagePlugin = __decorate([
@@ -130,0 +141,0 @@ (0, components_1.Component)({ name: "package" })

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

@@ -8,2 +8,3 @@ import type * as ts from "typescript";
 import type { Serializer, JSONOutput } from "../../serialization";
+import type { CommentDisplayPart } from "../comments";
 /**
@@ -113,2 +114,10 @@ * Stores hierarchical type data.
     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;
@@ -115,0 +124,0 @@ getAllSignatures(): SignatureReflection[];

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

@@ -42,2 +42,5 @@ import type { RendererHooks } from "../..";
     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;
@@ -44,0 +47,0 @@ toolbar: (props: import("../..").PageEvent<Reflection>) => import("../../../utils/jsx.elements").JsxElement;

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

@@ -71,2 +71,5 @@ "use strict";
         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);
@@ -73,0 +76,0 @@ this.toolbar = bind(toolbar_1.toolbar, this);

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

 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;

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

@@ -6,2 +6,3 @@ "use strict";
 const utils_1 = require("../../../../utils");
+const models_1 = require("../../../../models");
 const header = (context, props) => {
@@ -14,2 +15,5 @@ const HeadingLevel = props.model.isProject() ? "h2" : "h1";
             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,
@@ -16,0 +20,0 @@ "<",

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

 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;

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

@@ -6,2 +6,3 @@ "use strict";
 const utils_1 = require("../../../../utils");
+const models_1 = require("../../../../models");
 function renderCategory({ urlTo, icons }, item, prependName = "") {
@@ -40,5 +41,11 @@ return (utils_1.JSX.createElement("section", { class: "tsd-index-section" },
     }
-    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;

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

@@ -6,1 +6,4 @@ import { Reflection } from "../../../../models";
 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;

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

 "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");
@@ -9,5 +9,5 @@ const utils_1 = require("../../../../utils");
     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)));
 }
@@ -59,2 +59,3 @@ exports.navigation = navigation;
 }
+exports.settings = settings;
 function primaryNavigation(context, props) {
@@ -87,6 +88,7 @@ // Create the navigation for the current page
         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) {
@@ -123,2 +125,3 @@ // Multiple entry points, and on main project page.
 }
+exports.secondaryNavigation = secondaryNavigation;
 function inPath(thisPage, toCheck) {
@@ -125,0 +128,0 @@ while (toCheck) {

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

@@ -28,4 +28,6 @@ import * as ts from "typescript";
     displayName: string;
+    readmeFile?: string;
     program: ts.Program;
     sourceFile: ts.SourceFile;
+    version?: string;
 }
@@ -32,0 +34,0 @@ export declare function getEntryPoints(logger: Logger, options: Options): DocumentationEntryPoint[] | undefined;

dist/lib/utils/entry-point.js

@@ -7,2 +7,3 @@ "use strict";
 const FS = require("fs");
+const Path = require("path");
 const package_manifest_1 = require("./package-manifest");
@@ -209,2 +210,6 @@ const paths_1 = require("./paths");
         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) {
@@ -253,4 +258,14 @@ logger.error(`Could not load package manifest ${packageJsonPath}`);
         }
+        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,
@@ -257,0 +272,0 @@ sourceFile,

dist/lib/utils/loggers.js

@@ -101,12 +101,14 @@ "use strict";
     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);
     }
@@ -113,0 +115,0 @@ /** @internal */

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

 import type { Logger } from "./loggers";
 import type { IMinimatch } from "minimatch";
+import { additionalProperties, Infer } from "./validation";
 /**
@@ -7,3 +8,14 @@ * 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,
@@ -24,1 +36,2 @@ * return all the actual package folders found.
 export declare function getTsEntryPointForPackage(logger: Logger, packageJsonPath: string, packageJson: Record<string, unknown>): string | undefined | typeof ignorePackage;
+export {};

dist/lib/utils/package-manifest.js

 "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");
@@ -9,2 +9,3 @@ const fs_1 = require("fs");
 const paths_1 = require("./paths");
+const validation_1 = require("./validation");
 /**
@@ -31,3 +32,29 @@ * Helper for the TS type system to understand hasOwnProperty
 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
@@ -151,4 +178,9 @@ * Returns undefined if packageJSON does not define a Yarn workspace
     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;
@@ -155,0 +187,0 @@ }

package.json

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

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

1006143

increased by0.75%

Lines of code

23755

increased by0.55%

No dependency changes