@xpack/doxygen2docusaurus 2.0.0 → 2.1.0

package/src/docusaurus/cli-options.ts

@@ -0,0 +1,560 @@
+/*
+ * This file is part of the xPack project (http://xpack.github.io).
+ * Copyright (c) 2025-2026 Liviu Ionescu. All rights reserved.
+ *
+ * Permission to use, copy, modify, and/or distribute this software
+ * for any purpose is hereby granted, under the terms of the MIT license.
+ *
+ * If a copy of the license was not distributed with this file, it can
+ * be obtained from https://opensource.org/licenses/MIT.
+ */
+
+// ----------------------------------------------------------------------------
+
+import assert from 'node:assert'
+import * as fs from 'node:fs/promises'
+import * as path from 'node:path'
+// import * as util from 'node:util'
+
+// ----------------------------------------------------------------------------
+
+/**
+ * Redirect configuration for URL compatibility.
+ *
+ * @public
+ */
+export interface Redirects {
+  /** Source URL(s) to redirect from. */
+  from: string | string[]
+  /** Target URL to redirect to. */
+  to: string
+}
+
+/**
+ * Configuration options as specified by users in configuration files.
+ *
+ * @remarks
+ * All options are optional and can be either string or boolean values
+ * depending on the specific configuration property.
+ *
+ * @public
+ */
+export type CliConfigurationOptions = Record<string, string | boolean>
+
+/**
+ * Command line argument options passed to the application.
+ *
+ * @remarks
+ * Represents the parsed command line arguments with flexible typing
+ * to accommodate various option formats and undefined values.
+ *
+ * @public
+ */
+export type CommandOptions = Record<string, string | boolean | undefined>
+
+/**
+ * Multiple configuration sets for different build scenarios.
+ *
+ * @remarks
+ * Allows defining different configuration profiles that can be selected
+ * based on the build context or command line parameters.
+ *
+ * @public
+ */
+export type MultiConfigurations = Record<string, CliConfigurationOptions>
+
+/**
+ * Generic package.json structure for configuration discovery.
+ *
+ * @internal
+ */
+// Prefer config.doxygen2docusaurus, but also accept doxygen2docusaurus.
+interface GenericPackageConfiguration {
+  /** Nested configuration under the config property. */
+  config?: { doxygen2docusaurus: CliConfigurationOptions }
+  /** Direct configuration property. */
+  doxygen2docusaurus?: CliConfigurationOptions
+}
+
+/**
+ * Comprehensive CLI options class for documentation generation configuration.
+ *
+ * @remarks
+ * The CliOptions class contains all configuration parameters that control
+ * the behaviour of the doxygen2docusaurus conversion process, including
+ * paths, URLs, styling, and feature toggles.
+ *
+ * @public
+ */
+export class CliOptions {
+  /**
+   * Path to the Doxygen XML input folder relative to the website folder.
+   *
+   * @remarks
+   * Specifies the location of XML files generated by Doxygen, typically
+   * containing the parsed documentation data. Path should not include
+   * initial or final slashes.
+   *
+   * @defaultValue 'doxygen/xml'
+   */
+  doxygenXmlInputFolderPath = 'doxygen/xml'
+
+  /**
+   * Path to the documentation folder relative to the website folder.
+   *
+   * @remarks
+   * Defines the base folder where generated documentation will be placed
+   * within the Docusaurus website structure. Path should not include
+   * initial or final slashes.
+   *
+   * @defaultValue 'docs'
+   */
+  docsFolderPath = 'docs'
+
+  /**
+   * Path to the API documentation folder relative to the docs folder.
+   *
+   * @remarks
+   * Specifies the subfolder within the docs folder where API reference
+   * documentation will be generated. Path should not include initial
+   * or final slashes.
+   *
+   * @defaultValue 'api'
+   */
+  apiFolderPath = 'api'
+
+  /**
+   * Base URL for the entire website.
+   *
+   * @remarks
+   * Defines the root URL path for the website, typically '/' for root
+   * deployment or '/project-name/' for GitHub Pages or similar hosting.
+   *
+   * @defaultValue '/'
+   */
+  baseUrl = '/'
+
+  /**
+   * URL path to the documentation section relative to the website root.
+   *
+   * @remarks
+   * Specifies the URL segment that leads to the documentation section,
+   * without initial or final slashes. Used for navigation and linking.
+   *
+   * @defaultValue 'docs'
+   */
+  docsBaseUrl = 'docs'
+
+  /**
+   * URL path to the API documentation relative to the docs section.
+   *
+   * @remarks
+   * Defines the URL segment for API documentation within the docs section,
+   * without initial or final slashes. Used for generating navigation links.
+   *
+   * @defaultValue 'api'
+   */
+  apiBaseUrl = 'api'
+
+  /**
+   * Path for images relative to the `static` folder.
+   *
+   * @remarks
+   * Specifies where Doxygen-generated images will be stored within the
+   * Docusaurus static assets folder structure.
+   *
+   * @defaultValue 'assets/images/doxygen'
+   */
+  imagesFolderPath = 'assets/images/doxygen'
+
+  /**
+   * Output folder for compatibility redirect files.
+   *
+   * @remarks
+   * Optional path relative to the website/static folder where HTML redirect
+   * files will be generated to maintain compatibility with original Doxygen
+   * URLs. When undefined, no redirect files are created.
+   */
+  compatibilityRedirectsOutputFolderPath?: string | undefined
+
+  /**
+   * Title displayed on the main API documentation page.
+   *
+   * @remarks
+   * When specified, this title overrides the default title generated from
+   * the project brief. When empty, the title is automatically constructed
+   * from the project configuration.
+   *
+   * @defaultValue ''
+   */
+  mainPageTitle = ''
+
+  /**
+   * Path to the sidebar category configuration file.
+   *
+   * @remarks
+   * Specifies the location where the generated sidebar category JSON
+   * configuration will be written, relative to the current website folder.
+   *
+   * @defaultValue 'sidebar-category-doxygen.json'
+   */
+  sidebarCategoryFilePath = 'sidebar-category-doxygen.json'
+
+  /**
+   * Label displayed in the Docusaurus sidebar for the API documentation.
+   *
+   * @remarks
+   * Short descriptive text that appears in the sidebar navigation to
+   * identify the API reference section.
+   *
+   * @defaultValue 'API Reference (Doxygen)'
+   */
+  sidebarCategoryLabel = 'API Reference (Doxygen)'
+
+  /**
+   * Path to the navbar dropdown configuration file.
+   *
+   * @remarks
+   * Specifies the location where the generated navbar dropdown JSON
+   * configuration will be written, relative to the current website folder.
+   *
+   * @defaultValue 'docusaurus-config-navbar-doxygen.json'
+   */
+  navbarDropdownFilePath = 'docusaurus-config-navbar-doxygen.json'
+
+  /**
+   * Label displayed in the top navigation bar.
+   *
+   * @remarks
+   * Short text that appears in the Docusaurus top navigation bar to
+   * provide access to the API documentation section.
+   *
+   * @defaultValue 'API Reference'
+   */
+  navbarDropdownLabel = 'API Reference'
+
+  /**
+   * Position of the navigation menu in the top bar.
+   *
+   * @remarks
+   * Determines whether the API documentation menu appears on the left
+   * or right side of the Docusaurus navigation bar.
+   *
+   * @defaultValue 'left'
+   */
+  navbarDropdownPosition: 'left' | 'right' = 'left'
+
+  /**
+   * Path to the custom CSS file for styling overrides.
+   *
+   * @remarks
+   * Specifies the location where custom CSS styles will be written to
+   * provide Doxygen-specific styling within the Docusaurus theme.
+   * Path is relative to the current website folder.
+   *
+   * @defaultValue 'src/css/custom-doxygen2docusaurus.css'
+   */
+  customCssFilePath = 'src/css/custom-doxygen2docusaurus.css'
+
+  /**
+   * Controls verbose output during the conversion process.
+   *
+   * @remarks
+   * When enabled, provides detailed logging information about the
+   * conversion process, including file processing status and statistics.
+   *
+   * @defaultValue false
+   */
+  verbose = false
+
+  /**
+   * Controls debug-level output during the conversion process.
+   *
+   * @remarks
+   * When enabled, provides extensive debugging information useful for
+   * troubleshooting issues. Automatically enables verbose output as well.
+   *
+   * @defaultValue false
+   */
+  debug = false
+
+  /**
+   * Controls whether TODO suggestion descriptions are displayed.
+   *
+   * @remarks
+   * When enabled, shows suggestions for improvements or missing content
+   * that could enhance the generated documentation quality.
+   *
+   * @defaultValue false
+   */
+  suggestToDoDescriptions = false
+
+  /**
+   * Controls whether pages are listed at the top of the sidebar.
+   *
+   * @remarks
+   * When enabled, places page links prominently at the top of the sidebar
+   * navigation structure for easier access to important pages.
+   *
+   * @defaultValue true
+   */
+  listPagesAtTop = true
+
+  /**
+   * Controls program listing rendering in File pages.
+   *
+   * @remarks
+   * When enabled, includes syntax-highlighted source code listings
+   * within the generated File documentation pages.
+   *
+   * @defaultValue true
+   */
+  renderProgramListing = true
+
+  /**
+   * Controls program listing rendering in member definition sections.
+   *
+   * @remarks
+   * When enabled, includes inline syntax-highlighted code snippets
+   * within member documentation sections for better context.
+   *
+   * @defaultValue true
+   */
+  renderProgramListingInline = true
+
+  /**
+   * Note about the location of original Doxygen pages.
+   *
+   * @remarks
+   * Provides information about where to find the original Doxygen HTML
+   * pages for comparison purposes. When populated, this note is displayed
+   * to inform users about the availability of alternative documentation
+   * formats.
+   */
+  originalPagesNote = ''
+
+  /**
+   * String identifier for distinguishing multiple configuration instances.
+   *
+   * @remarks
+   * Used when multiple configuration instances exist to provide unique
+   * identification. Particularly useful in multi-configuration scenarios
+   * where different settings need to be applied to different outputs.
+   *
+   * @defaultValue 'default'
+   */
+  id = 'default'
+
+  /**
+   * Creates a new CliOptions instance with the specified command options.
+   *
+   * @remarks
+   * Initialises the configuration object by setting the ID and optional
+   * flags like verbose and debug. When the ID is not 'default', adjusts
+   * folder paths and file names to include the ID for multi-configuration
+   * scenarios.
+   *
+   * @param commandOptions - Command-line options object containing ID and flags
+   */
+  constructor(commandOptions: CommandOptions) {
+    this.id = commandOptions.id as string
+
+    if (commandOptions.verbose !== undefined) {
+      this.verbose = true
+    }
+
+    if (commandOptions.debug !== undefined) {
+      this.debug = true
+    }
+
+    if (this.id !== 'default') {
+      this.apiFolderPath = this.id
+      this.apiBaseUrl = this.id
+      this.imagesFolderPath = `img/doxygen-${this.id}`
+      this.sidebarCategoryFilePath =
+        'sidebar-category-doxygen' + `-${this.id}.json`
+      this.navbarDropdownFilePath =
+        'docusaurus-config-navbar-doxygen' + `-${this.id}.json`
+    } else {
+      this.apiFolderPath = 'api'
+      this.apiBaseUrl = 'api'
+      this.imagesFolderPath = `img/doxygen`
+      this.sidebarCategoryFilePath = `sidebar-category-doxygen.json`
+      this.navbarDropdownFilePath = `docusaurus-config-navbar-doxygen.json`
+    }
+  }
+
+  /**
+   * Parses configuration options from various JSON configuration sources.
+   *
+   * @remarks
+   * Attempts to load configuration from multiple locations in order of
+   * preference: config/doxygen2docusaurus.json, doxygen2docusaurus.json,
+   * and package.json. Validates required properties and enables debug
+   * output if requested.
+   *
+   * @throws Assertion error if required configuration properties are missing
+   */
+  async parse(): Promise<void> {
+    let configurationOptions: CliConfigurationOptions | undefined = undefined
+
+    try {
+      const userPackageJsonPath = path.resolve(
+        process.cwd(),
+        'config',
+        'doxygen2docusaurus.json'
+      )
+      const pkgJsonRaw = await fs.readFile(userPackageJsonPath, 'utf8')
+
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+      const multiConfigurations: MultiConfigurations = JSON.parse(pkgJsonRaw)
+
+      configurationOptions = this.selectMultiConfiguration(multiConfigurations)
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    } catch (err) {
+      /* Cannot read/parse JSON */
+    }
+
+    if (configurationOptions === undefined) {
+      try {
+        const userPackageJsonPath = path.resolve(
+          process.cwd(),
+          'doxygen2docusaurus.json'
+        )
+        const pkgJsonRaw = await fs.readFile(userPackageJsonPath, 'utf8')
+
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        const multiConfigurations: MultiConfigurations = JSON.parse(pkgJsonRaw)
+
+        configurationOptions =
+          this.selectMultiConfiguration(multiConfigurations)
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      } catch (err) {
+        /* Cannot read/parse JSON */
+      }
+    }
+
+    if (configurationOptions === undefined) {
+      try {
+        // Try to get the configuration from
+        // package.json/[config/]doxygen2docusaurus.
+        const userPackageJsonPath = path.resolve(process.cwd(), 'package.json')
+        const pkgJsonRaw = await fs.readFile(userPackageJsonPath, 'utf8')
+
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        const pkgJson: GenericPackageConfiguration = JSON.parse(pkgJsonRaw)
+
+        const multiConfigurations:
+          | CliConfigurationOptions
+          | MultiConfigurations
+          | undefined =
+          pkgJson.config?.doxygen2docusaurus ?? pkgJson.doxygen2docusaurus
+
+        if (multiConfigurations !== undefined) {
+          configurationOptions =
+            this.selectMultiConfiguration(multiConfigurations)
+        }
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      } catch (err) {
+        /* Cannot read/parse JSON */
+      }
+    }
+
+    if (configurationOptions !== undefined) {
+      if (this.debug) {
+        console.log(configurationOptions)
+      }
+      // Override only properties that exist in CliOptions
+      const thisProperties = Object.getOwnPropertyNames(this)
+
+      for (const key of Object.keys(configurationOptions)) {
+        const value: unknown = configurationOptions[key]
+        // console.log(key, value)
+        if (value !== undefined && thisProperties.includes(key)) {
+          const thisProperty = (this as Record<string, unknown>)[key]
+          const thisType = typeof thisProperty
+          const valueType = typeof value
+
+          // if (['id', 'verbose', 'debug'].includes(key)) {
+          if (['id'].includes(key)) {
+            continue
+          }
+
+          // Override only if types match.
+          if (thisType === valueType) {
+            ;(this as Record<string, unknown>)[key] = value
+          }
+        }
+      }
+    }
+
+    if (this.debug) {
+      this.verbose = true
+    }
+
+    if (this.verbose) {
+      console.log()
+      console.log(this)
+    }
+
+    assert(
+      this.doxygenXmlInputFolderPath.length > 0,
+      'doxygenXmlInputFolderPath is required'
+    )
+
+    assert(this.docsFolderPath.length > 0, 'docsFolderPath is required')
+    assert(this.apiFolderPath.length > 0, 'apiFolderPath is required')
+
+    assert(this.docsBaseUrl.length > 0, 'docsBaseUrl is required')
+    // assert(this.apiBaseUrl.length > 0, 'apiBaseUrl is required')
+
+    assert(
+      this.sidebarCategoryFilePath.length > 0,
+      'sidebarCategoryFilePath is required'
+    )
+  }
+
+  /**
+   * Selects the appropriate configuration from multi-configuration options.
+   *
+   * @remarks
+   * When using a specific ID, returns the corresponding configuration.
+   * For the default ID, returns either the 'default' configuration or
+   * treats the entire object as a single configuration.
+   *
+   * @param multiConfigurations - Configuration object or multi-config map
+   * @returns Selected configuration options or undefined if not found
+   */
+  selectMultiConfiguration(
+    multiConfigurations: CliConfigurationOptions | MultiConfigurations
+  ): CliConfigurationOptions | undefined {
+    let configurationOptions: CliConfigurationOptions | undefined = undefined
+    if (this.id !== 'default') {
+      configurationOptions = (
+        multiConfigurations as Record<
+          string,
+          CliConfigurationOptions | undefined
+        >
+      )[this.id]
+
+      if (configurationOptions !== undefined) {
+        configurationOptions.id = this.id
+      }
+    } else {
+      const multiConfig = multiConfigurations as MultiConfigurations
+      configurationOptions =
+        'default' in multiConfig
+          ? multiConfig.default
+          : (multiConfigurations as CliConfigurationOptions)
+    }
+    return configurationOptions
+  }
+}
+
+// Was used during development. Now stick to true.
+export const renderParagraphs = true
+
+// Does not make noticeable differences.
+export const maxParallelPromises = 42
+
+// ----------------------------------------------------------------------------