Support readme only packages

Resolves #2264

Author: Gerrit0

Diff for: CHANGELOG.md

@@ -1,5 +1,9 @@
 # Unreleased
 
+### Features
+
+-   TypeDoc will now allow conversion without any entry points to support "readme only" packages, #2264.
+
 ### Bug Fixes
 
 -   Category children are now sorted according to the `sort` option, #2272.

Diff for: src/lib/application.ts

@@ -516,6 +516,13 @@ export class Application extends ChildableComponent<
     }
 
     private _convertPackages(): ProjectReflection | undefined {
+        if (!this.options.isSet("entryPoints")) {
+            this.logger.error(
+                "No entry points provided to packages mode, documentation cannot be generated."
+            );
+            return;
+        }
+
         const packageDirs = getPackageDirectories(
             this.logger,
             this.options,
@@ -535,7 +542,7 @@ export class Application extends ChildableComponent<
         // Generate a json file for each package
         for (const dir of packageDirs) {
             this.logger.info(`Converting project at ${nicePath(dir)}`);
-            const opts = origOptions.copyForPackage();
+            const opts = origOptions.copyForPackage(dir);
             // Invalid links should only be reported after everything has been merged.
             opts.setValue("validation", { invalidLink: false });
             opts.read(this.logger, dir);
@@ -584,6 +591,11 @@ export class Application extends ChildableComponent<
     private _merge(): ProjectReflection | undefined {
         const start = Date.now();
 
+        if (!this.options.isSet("entryPoints")) {
+            this.logger.error("No entry points provided to merge.");
+            return;
+        }
+
         const rootDir = deriveRootDir(this.entryPoints);
         const entryPoints = this.entryPoints.flatMap((entry) => {
             const result = glob(entry, rootDir);
@@ -605,11 +617,6 @@ export class Application extends ChildableComponent<
             return result;
         });
 
-        if (entryPoints.length < 1) {
-            this.logger.error("No entry points provided to merge.");
-            return;
-        }
-
         const jsonProjects = entryPoints.map((path) => {
             try {
                 return JSON.parse(readFile(path));

Diff for: src/lib/converter/plugins/PackagePlugin.ts

@@ -81,7 +81,9 @@ export class PackagePlugin extends ConverterComponent {
                 ? this.entryPoints.map((d) => join(d, "package.json"))
                 : this.entryPoints;
 
-        const dirName = Path.resolve(deriveRootDir(entryFiles));
+        const dirName =
+            this.application.options.packageDir ??
+            Path.resolve(deriveRootDir(entryFiles));
 
         this.application.logger.verbose(
             `Begin readme.md/package.json search at ${nicePath(dirName)}`

Diff for: src/lib/output/themes/default/partials/index.tsx

@@ -1,7 +1,7 @@
 import { classNames, renderName } from "../../lib";
 import type { DefaultThemeRenderContext } from "../DefaultThemeRenderContext";
-import { JSX, Raw } from "../../../../utils";
-import { ContainerReflection, DeclarationReflection, ReflectionCategory, ReflectionKind } from "../../../../models";
+import { JSX } from "../../../../utils";
+import type { ContainerReflection, ReflectionCategory } from "../../../../models";
 
 function renderCategory(
     { urlTo, icons, getReflectionClasses }: DefaultThemeRenderContext,
@@ -72,15 +72,6 @@ export function index(context: DefaultThemeRenderContext, props: ContainerReflec
 
     return (
         <>
-            {props instanceof DeclarationReflection &&
-                props.kind === ReflectionKind.Module &&
-                props.readme?.length !== 0 && (
-                    <section class="tsd-panel-group">
-                        <section class="tsd-panel tsd-typography">
-                            <Raw html={context.markdown(props.readme || [])} />
-                        </section>
-                    </section>
-                )}
             <section class="tsd-panel-group tsd-index-group">
                 <section class="tsd-panel tsd-index-panel">{content}</section>
             </section>

Diff for: src/lib/output/themes/default/templates/reflection.tsx

@@ -2,7 +2,7 @@ import { classNames, hasTypeParameters } from "../../lib";
 import type { DefaultThemeRenderContext } from "../DefaultThemeRenderContext";
 import type { PageEvent } from "../../../events";
 import { ContainerReflection, DeclarationReflection, ReflectionKind, ReflectionType } from "../../../../models";
-import { JSX } from "../../../../utils";
+import { JSX, Raw } from "../../../../utils";
 
 export function reflectionTemplate(context: DefaultThemeRenderContext, props: PageEvent<ContainerReflection>) {
     if (
@@ -18,6 +18,14 @@ export function reflectionTemplate(context: DefaultThemeRenderContext, props: Pa
                 <section class="tsd-panel tsd-comment">{context.comment(props.model)}</section>
             )}
 
+            {props.model instanceof DeclarationReflection &&
+                props.model.kind === ReflectionKind.Module &&
+                props.model.readme?.length && (
+                    <section class="tsd-panel tsd-typography">
+                        <Raw html={context.markdown(props.model.readme)} />
+                    </section>
+                )}
+
             {hasTypeParameters(props.model) && <> {context.typeParameters(props.model.typeParameters)} </>}
             {props.model instanceof DeclarationReflection && (
                 <>

Diff for: src/lib/utils/entry-point.ts

@@ -62,11 +62,19 @@ export function getEntryPoints(
     logger: Logger,
     options: Options
 ): DocumentationEntryPoint[] | undefined {
+    if (!options.isSet("entryPoints")) {
+        logger.warn(
+            "No entry points were provided, this is likely a misconfiguration."
+        );
+        return [];
+    }
+
     const entryPoints = options.getValue("entryPoints");
 
+    // May be set explicitly to be an empty array to only include a readme for a package
+    // See #2264
     if (entryPoints.length === 0) {
-        logger.error("No entry points were provided.");
-        return;
+        return [];
     }
 
     let result: DocumentationEntryPoint[] | undefined;
@@ -181,7 +189,7 @@ function getEntryPointsForPaths(
     inputFiles: string[],
     options: Options,
     programs = getEntryPrograms(logger, options)
-): DocumentationEntryPoint[] | undefined {
+): DocumentationEntryPoint[] {
     const baseDir = options.getValue("basePath") || deriveRootDir(inputFiles);
     const entryPoints: DocumentationEntryPoint[] = [];
 
@@ -232,7 +240,7 @@ export function getExpandedEntryPointsForPaths(
     inputFiles: string[],
     options: Options,
     programs = getEntryPrograms(logger, options)
-): DocumentationEntryPoint[] | undefined {
+): DocumentationEntryPoint[] {
     return getEntryPointsForPaths(
         logger,
         expandInputFiles(logger, inputFiles, options),

Diff for: src/lib/utils/options/options.ts

@@ -95,6 +95,11 @@ export class Options {
     private _projectReferences: readonly ts.ProjectReference[] = [];
     private _logger: Logger;
 
+    /**
+     * In packages mode, the directory of the package being converted.
+     */
+    packageDir?: string;
+
     constructor(logger: Logger) {
         this._logger = logger;
         addTypeDocOptions(this);
@@ -103,8 +108,9 @@ export class Options {
     /**
      * Clones the options, intended for use in packages mode.
      */
-    copyForPackage(): Options {
+    copyForPackage(packageDir: string): Options {
         const options = new Options(this._logger);
+        options.packageDir = packageDir;
 
         options._readers = this._readers.filter(
             (reader) => reader.supportsPackages