Support readme only packages

Resolves #2264

Author: Gerrit0

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.

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));

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)}`

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>

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 && (
  <>

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),

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