Only search for readme next to package.json

Resolves #2875

Author: Gerrit0

CHANGELOG.md

@@ -11,6 +11,8 @@ title: Changelog
 - Removed `jp` translations from `lang`, to migrate switch to `ja`.
 - File name references in `intentionallyNotExported` now use a package name/package relative path instead of an absolute path for matching.
 - The `source-order` sort ordering now considers package names / package relative paths instead of using the absolute paths to a file.
+- TypeDoc will only check for a project README file next to the discovered `package.json` file if `--readme` is not set
+  this change improves handling of monorepo setups where some packages have readme files and others do not, #2875.
 
 ### API Breaking Changes
 

scripts/testcase.js

@@ -58,7 +58,7 @@ async function main() {
     if (!code) {
         console.log("No codeblock found");
         const file = `src/test/converter2/issues/gh${issue}.ts`;
-        await exec(`code ${file}`);
+        await exec(`code ${file} src/test/issues.c2.test.ts`);
         return;
     }
 

src/lib/converter/plugins/PackagePlugin.ts

@@ -8,7 +8,6 @@ import { ConverterEvents } from "../converter-events.js";
 import type { Converter } from "../converter.js";
 import { type GlobString, i18n, MinimalSourceFile, type NormalizedPath } from "#utils";
 import {
-    discoverInParentDir,
     discoverPackageJson,
     type EntryPointStrategy,
     getCommonDirectory,
@@ -17,6 +16,7 @@ import {
     Option,
     readFile,
 } from "#node-utils";
+import { existsSync } from "fs";
 
 /**
  * A handler that tries to find the package.json and readme.md files of the
@@ -82,10 +82,11 @@ export class PackagePlugin extends ConverterComponent {
             Path.resolve(getCommonDirectory(this.entryPoints.map(g => `${g}/`)));
 
         this.application.logger.verbose(
-            `Begin readme.md/package.json search at ${nicePath(dirName)}`,
+            `Begin package.json search at ${nicePath(dirName)}`,
         );
 
-        this.packageJson = discoverPackageJson(dirName)?.content;
+        const packageJson = discoverPackageJson(dirName);
+        this.packageJson = packageJson?.content;
 
         // Path will be resolved already. This is kind of ugly, but...
         if (this.readme.endsWith("none")) {
@@ -105,17 +106,22 @@ export class PackagePlugin extends ConverterComponent {
                     ),
                 );
             }
-        } else {
+        } else if (packageJson) {
             // No readme provided, automatically find the readme
-            const result = discoverInParentDir(
+            const possibleReadmePaths = [
+                "README.md",
                 "readme.md",
-                dirName,
-                (content) => content,
-            );
+                "Readme.md",
+            ].map(name => Path.join(Path.dirname(packageJson.file), name));
+
+            const readmePath = possibleReadmePaths.find(path => {
+                this.application.watchFile(path);
+                return existsSync(path);
+            });
 
-            if (result) {
-                this.readmeFile = normalizePath(result.file);
-                this.readmeContents = result.content;
+            if (readmePath) {
+                this.readmeFile = normalizePath(readmePath);
+                this.readmeContents = readFile(readmePath);
                 this.application.watchFile(this.readmeFile);
             }
         }

src/lib/utils/fs.ts

@@ -260,32 +260,6 @@ export function hasDeclarationFileExtension(path: string) {
     return /\.d\.[cm]?ts$/.test(path);
 }
 
-export function discoverInParentDir<T extends {}>(
-    name: string,
-    dir: string,
-    read: (content: string) => T | undefined,
-): { file: string; content: T } | undefined {
-    if (!isDir(dir)) return;
-
-    const reachedTopDirectory = (dirName: string) => dirName === resolve(join(dirName, ".."));
-
-    while (!reachedTopDirectory(dir)) {
-        for (const file of fs.readdirSync(dir)) {
-            if (file.toLowerCase() !== name.toLowerCase()) continue;
-
-            try {
-                const content = read(readFile(join(dir, file)));
-                if (content != null) {
-                    return { file: join(dir, file), content };
-                }
-            } catch {
-                // Ignore, file didn't pass validation
-            }
-        }
-        dir = resolve(join(dir, ".."));
-    }
-}
-
 export function discoverInParentDirExactMatch<T extends {}>(
     name: string,
     dir: string,

src/test/behavior.c2.test.ts

@@ -1396,4 +1396,10 @@ describe("Behavior Tests", () => {
             "error: @include *#circular* resulted in a circular include:*",
         );
     });
+
+    it("#2875 discovers readme files directly adjacent to the package.json file", () => {
+        const project = convert("asConstEnum");
+        // Previously, would find TypeDoc's root readme
+        equal(project.readme, undefined);
+    });
 });

src/test/converter2/package.json

@@ -1,3 +1,5 @@
 {
+    "name": "typedoc",
+    "private": true,
     "type": "commonjs"
 }

src/test/output/router.test.ts

@@ -178,6 +178,7 @@ describe("KindRouter", () => {
 
     it("Can link to the modules page", () => {
         const project = getProject();
+        project.readme = [{ kind: "text", text: "Needed so we create a modules page" }];
         const router = new KindRouter(app);
         router.buildPages(project);