feat: add errorOnEmptyDocumentation option (#74)

Author: HiDeoo

.changeset/strange-mangos-pretend.md

@@ -0,0 +1,9 @@
+---
+'starlight-typedoc': minor
+---
+
+Adds a new [`errorOnEmptyDocumentation`](https://starlight-typedoc.vercel.app/configuration/#erroronemptydocumentation) option, defaulting to `true`, to control whether the plugin should error when no TypeDoc documentation is generated.
+
+Setting this option to `false` will prevent the plugin from erroring in this case which can be useful when generating documentation for multiple entry points and only some of them contain documented code at a given time.
+
+The current behavior remains unchanged, and the plugin will error when no TypeDoc documentation is generated if the option is not explicitly set to `false`.

docs/src/content/docs/configuration.md

@@ -79,6 +79,17 @@ As documented in the [TypeDoc documentation](https://typedoc.org/options/input/#
 
 Whether to watch the entry point(s) for changes and regenerate the documentation when needed.
 
+### `errorOnEmptyDocumentation`
+
+**Type:** `boolean`  
+**Default:** `true`
+
+Whether the plugin should error when no TypeDoc documentation is generated.
+
+By default, the plugin will error when no TypeDoc documentation is generated.
+Setting this option to `false` will prevent the plugin from erroring in this case.
+This can be useful when generating documentation for multiple entry points and only some of them contain documented code at a given time.
+
 ## Sidebar configuration
 
 The sidebar configuration is an object with the following properties:

packages/starlight-typedoc/index.ts

@@ -3,8 +3,13 @@ import { randomBytes } from 'node:crypto'
 import type { StarlightPlugin } from '@astrojs/starlight/types'
 import type { TypeDocOptions } from 'typedoc'
 
-import { getSidebarFromReflections, getSidebarGroupPlaceholder, type SidebarGroup } from './libs/starlight'
-import { generateTypeDoc, type TypeDocConfig } from './libs/typedoc'
+import {
+  getSidebarFromReflections,
+  getSidebarGroupPlaceholder,
+  getSidebarWithoutReflections,
+  type SidebarGroup,
+} from './libs/starlight'
+import { generateTypeDoc, NoReflectionsError, type TypeDocConfig } from './libs/typedoc'
 
 export const typeDocSidebarGroup = getSidebarGroupPlaceholder()
 
@@ -26,16 +31,27 @@ function makeStarlightTypeDocPlugin(sidebarGroup: SidebarGroup): (options: Starl
         async 'config:setup'({ astroConfig, command, config, logger, updateConfig }) {
           if (command === 'preview') return
 
-          const { outputDirectory, reflections } = await generateTypeDoc(options, astroConfig, logger)
-          const sidebar = getSidebarFromReflections(
-            config.sidebar,
-            sidebarGroup,
-            options.sidebar,
-            reflections,
-            outputDirectory,
-          )
+          try {
+            const { outputDirectory, reflections } = await generateTypeDoc(options, astroConfig, logger)
 
-          updateConfig({ sidebar })
+            updateConfig({
+              sidebar: getSidebarFromReflections(
+                config.sidebar,
+                sidebarGroup,
+                options.sidebar,
+                reflections,
+                outputDirectory,
+              ),
+            })
+          } catch (error) {
+            if (options.errorOnEmptyDocumentation === false && error instanceof NoReflectionsError) {
+              logger.warn('No documentation generated but ignoring as `errorOnEmptyDocumentation` is disabled.')
+              updateConfig({ sidebar: getSidebarWithoutReflections(config.sidebar, sidebarGroup) })
+              return
+            }
+
+            throw error
+          }
         },
       },
     }
@@ -47,6 +63,11 @@ export interface StarlightTypeDocOptions {
    * The path(s) to the entry point(s) to document.
    */
   entryPoints: TypeDocOptions['entryPoints']
+  /**
+   * Whether the plugin should error when no TypeDoc documentation is generated.
+   * @default true
+   */
+  errorOnEmptyDocumentation?: boolean
   /**
    * The output directory containing the generated documentation markdown files relative to the `src/content/docs/`
    * directory.

packages/starlight-typedoc/libs/starlight.ts

@@ -63,6 +63,39 @@ export function getSidebarFromReflections(
   })
 }
 
+export function getSidebarWithoutReflections(
+  sidebar: StarlightUserConfigSidebar,
+  sidebarGroupPlaceholder: SidebarGroup,
+): StarlightUserConfigSidebar {
+  if (!sidebar || sidebar.length === 0) {
+    return sidebar
+  }
+
+  function removeSidebarGroupPlaceholder(
+    entries: NonNullable<StarlightUserConfigSidebar>,
+  ): NonNullable<StarlightUserConfigSidebar> {
+    const sidebarWithoutPlaceholder: StarlightUserConfigSidebar = []
+
+    for (const item of entries) {
+      if (isSidebarManualGroup(item)) {
+        if (item.label === sidebarGroupPlaceholder.label) continue
+
+        sidebarWithoutPlaceholder.push({
+          ...item,
+          items: removeSidebarGroupPlaceholder(item.items),
+        })
+        continue
+      }
+
+      sidebarWithoutPlaceholder.push(item)
+    }
+
+    return sidebarWithoutPlaceholder
+  }
+
+  return removeSidebarGroupPlaceholder(sidebar)
+}
+
 function getSidebarGroupFromPackageReflections(
   options: StarlightTypeDocSidebarOptions,
   reflections: ProjectReflection | DeclarationReflection,

packages/starlight-typedoc/libs/typedoc.ts

@@ -58,7 +58,7 @@ export async function generateTypeDoc(
     (!reflections?.groups || reflections.groups.length === 0) &&
     !reflections?.children?.some((child) => (child.groups ?? []).length > 0)
   ) {
-    throw new Error('Failed to generate TypeDoc documentation.')
+    throw new NoReflectionsError()
   }
 
   const outputPath = path.join(url.fileURLToPath(config.srcDir), 'content/docs', outputDirectory)
@@ -159,4 +159,10 @@ function onRendererEnd(pagesToRemove: string[]) {
   }
 }
 
+export class NoReflectionsError extends Error {
+  constructor() {
+    super('Failed to generate TypeDoc documentation.')
+  }
+}
+
 export type TypeDocConfig = Partial<Omit<TypeDocOptions, 'entryPoints' | 'tsconfig'> & PluginOptions>