@xpack/doxygen2docusaurus 2.0.0 → 2.1.0

package/src/docusaurus/renderers/doctitletype.ts

@@ -0,0 +1,77 @@
+/*
+ * 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 util from 'node:util'
+
+import { ElementLinesRendererBase } from './element-renderer-base.js'
+import {
+  type AbstractDocTitleType,
+  TermDataModel,
+  TitleDataModel,
+} from '../../doxygen/data-model/compounds/descriptiontype-dm.js'
+
+// ----------------------------------------------------------------------------
+
+/**
+ * Renderer for Doxygen document title elements.
+ *
+ * @remarks
+ * Handles title and term elements within documentation structures.
+ * Supports polymorphic rendering for different title types while
+ * providing error handling for unrecognised element variations.
+ *
+ * @public
+ */
+export class DocTitleTypeLinesRenderer extends ElementLinesRendererBase {
+  /**
+   * Renders a document title element to formatted output lines.
+   *
+   * @remarks
+   * Processes title and term data models by rendering their child elements.
+   * Logs errors for unrecognised title types that require implementation
+   * support for complete documentation coverage.
+   *
+   * @param element - The document title element to render
+   * @param type - The rendering context type
+   * @returns Array containing the rendered title text
+   */
+  override renderToLines(
+    element: AbstractDocTitleType,
+    type: string
+  ): string[] {
+    // console.log(util.inspect(element, { compact: false, depth: 999 }))
+
+    let text = ''
+
+    if (element instanceof TitleDataModel) {
+      text += this.workspace.renderElementsArrayToString(element.children, type)
+    } else if (element instanceof TermDataModel) {
+      text += this.workspace.renderElementsArrayToString(element.children, type)
+    } else {
+      console.error(
+        element.constructor.name,
+        'not rendered in',
+        this.constructor.name
+      )
+      // text += '<b>'
+      // text +=
+      //   this.workspace.renderElementsArrayToString(element.children, type)
+      // text += '</b>'
+    }
+
+    return [text]
+  }
+}
+
+// ----------------------------------------------------------------------------

package/src/docusaurus/renderers/docvariablelisttype.ts

@@ -0,0 +1,123 @@
+/*
+ * 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 util from 'node:util'
+
+import { ElementLinesRendererBase } from './element-renderer-base.js'
+import type {
+  AbstractDocVariableListType,
+  VariableListPairDataModel,
+} from '../../doxygen/data-model/compounds/docvarlistentrytype-dm.js'
+
+// ----------------------------------------------------------------------------
+
+/**
+ * Renderer for Doxygen variable list container elements.
+ *
+ * @remarks
+ * Creates HTML definition list structure for variable lists containing
+ * term-description pairs. Provides the outer container for organised
+ * presentation of variable documentation.
+ *
+ * @public
+ */
+export class DocVariableListTypeLinesRenderer extends ElementLinesRendererBase {
+  /**
+   * Renders a variable list container to formatted output lines.
+   *
+   * @remarks
+   * Creates an HTML definition list wrapper around variable list entries.
+   * Each child element represents a term-description pair within the
+   * structured list format.
+   *
+   * @param element - The variable list container element to render
+   * @param type - The rendering context type (unused in implementation)
+   * @returns Array of HTML strings forming the definition list structure
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  renderToLines(element: AbstractDocVariableListType, type: string): string[] {
+    // console.log(util.inspect(element, { compact: false, depth: 999 }))
+
+    const lines: string[] = []
+
+    lines.push('')
+    lines.push('<dl class="doxyVariableList">')
+    lines.push(
+      ...this.workspace.renderElementsArrayToLines(element.children, 'html')
+    )
+    lines.push('</dl>')
+
+    return lines
+  }
+}
+
+/**
+ * Renderer for individual variable list entry pairs.
+ *
+ * @remarks
+ * Converts term-description pairs into HTML definition list items.
+ * Handles both single-line and multi-line descriptions with appropriate
+ * formatting for readable documentation output.
+ *
+ * @public
+ */
+export class VariableListPairLinesRenderer extends ElementLinesRendererBase {
+  /**
+   * Renders a variable list entry pair to formatted output lines.
+   *
+   * @remarks
+   * Creates HTML definition term and description elements from the
+   * variable list entry. Handles multi-line descriptions by splitting
+   * content across multiple lines within the definition element.
+   *
+   * @param element - The variable list pair element to render
+   * @param type - The rendering context type (unused in implementation)
+   * @returns Array of HTML strings for the term-description pair
+   */
+  override renderToLines(
+    element: VariableListPairDataModel,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    type: string
+  ): string[] {
+    // console.log(util.inspect(element, { compact: false, depth: 999 }))
+
+    const lines: string[] = []
+
+    // console.log(element.varlistentry.term)
+    // console.log(element.listitem.paras)
+
+    // WARNING: the title includes <b></b>
+    const title = this.workspace
+      .renderElementToString(element.varlistentry.term, 'html')
+      .trim()
+
+    // this.workspace.skipElementsPara(element.listitem.paras)
+    const description = this.workspace
+      .renderElementsArrayToString(element.listitem.paras, 'html')
+      .trim()
+
+    lines.push(`<dt>${title}</dt>`)
+    if (!description.includes('\n')) {
+      lines.push(`<dd>${description}</dd>`)
+    } else {
+      lines.push('<dd>')
+      lines.push(...description.split('\n'))
+      lines.push('</dd>')
+    }
+
+    return lines
+  }
+}
+
+// ----------------------------------------------------------------------------

package/src/docusaurus/renderers/docxrefsecttype.ts

@@ -0,0 +1,84 @@
+/*
+ * 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 util from 'node:util'
+
+import { ElementLinesRendererBase } from './element-renderer-base.js'
+import type { AbstractDocXRefSectType } from '../../doxygen/data-model/compounds/descriptiontype-dm.js'
+
+// ----------------------------------------------------------------------------
+
+/**
+ * Renderer for Doxygen cross-reference section elements.
+ *
+ * @remarks
+ * Generates HTML structure for cross-reference sections with titles and
+ * descriptions. Creates definition lists with linked titles and detailed
+ * content for documentation cross-references.
+ *
+ * @public
+ */
+export class DocXRefSectLinesRenderer extends ElementLinesRendererBase {
+  /**
+   * Renders a cross-reference section to formatted output lines.
+   *
+   * @remarks
+   * Creates an HTML definition list structure with the cross-reference
+   * title as a linked term and the description as the definition content.
+   * Generates a permalink for the cross-reference section.
+   *
+   * @param element - The cross-reference section element to render
+   * @param type - The rendering context type (unused in implementation)
+   * @returns Array of HTML strings forming the cross-reference section
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  renderToLines(element: AbstractDocXRefSectType, type: string): string[] {
+    // console.log(util.inspect(element, { compact: false, depth: 999 }))
+
+    const lines: string[] = []
+
+    const title = this.workspace.renderString(
+      element.xreftitle ?? '???',
+      'html'
+    )
+    const permalink = this.workspace.getPermalink({
+      refid: element.id,
+      kindref: 'xrefsect',
+    })
+    assert(permalink !== undefined)
+
+    lines.push('')
+    lines.push('<div class="doxyXrefSect">')
+    lines.push('<dl class="doxyXrefSectList">')
+    lines.push(
+      `<dt class="doxyXrefSectTitle"><a href=${permalink}>${title}</a></dt>`
+    )
+    lines.push('<dd class="doxyXrefSectDescription">')
+
+    if (element.xrefdescription !== undefined) {
+      lines.push(
+        this.workspace
+          .renderElementToString(element.xrefdescription, 'html')
+          .trim()
+      )
+    }
+    lines.push('</dd>')
+    lines.push('</dl>')
+    lines.push('</div>')
+
+    return lines
+  }
+}
+
+// ----------------------------------------------------------------------------

package/src/docusaurus/renderers/element-renderer-base.ts

@@ -0,0 +1,112 @@
+/*
+ * 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 type { Workspace } from '../workspace.js'
+
+// ----------------------------------------------------------------------------
+
+/**
+ * Abstract base class for renderers that output string content.
+ *
+ * @remarks
+ * Provides common functionality for element renderers that convert
+ * Doxygen XML elements into formatted string output. Maintains a
+ * reference to the workspace for accessing configuration and utilities.
+ *
+ * @public
+ */
+export abstract class ElementStringRendererBase {
+  /**
+   * The workspace containing global configuration and utilities.
+   *
+   * @remarks
+   * Provides access to rendering utilities, permalink generation,
+   * and global configuration options needed for element processing.
+   */
+  workspace: Workspace
+
+  /**
+   * Creates a new string element renderer.
+   *
+   * @remarks
+   * Initialises the renderer with the workspace reference for accessing
+   * global configuration and rendering utilities.
+   *
+   * @param workspace - The workspace instance
+   */
+  constructor(workspace: Workspace) {
+    this.workspace = workspace
+  }
+
+  /**
+   * Renders an element to a formatted string.
+   *
+   * @remarks
+   * Abstract method that must be implemented by derived classes to
+   * convert specific element types into their string representation.
+   *
+   * @param element - The element to render
+   * @param type - The rendering context type
+   * @returns Formatted string output
+   */
+  abstract renderToString(element: object, type: string): string
+}
+
+/**
+ * Abstract base class for renderers that output multiple lines.
+ *
+ * @remarks
+ * Provides common functionality for element renderers that convert
+ * Doxygen XML elements into formatted multi-line output. Maintains
+ * a reference to the workspace for accessing configuration and utilities.
+ *
+ * @public
+ */
+export abstract class ElementLinesRendererBase {
+  /**
+   * The workspace containing global configuration and utilities.
+   *
+   * @remarks
+   * Provides access to rendering utilities, permalink generation,
+   * and global configuration options needed for element processing.
+   */
+  workspace: Workspace
+
+  /**
+   * Creates a new lines element renderer.
+   *
+   * @remarks
+   * Initialises the renderer with the workspace reference for accessing
+   * global configuration and rendering utilities.
+   *
+   * @param workspace - The workspace instance
+   */
+  constructor(workspace: Workspace) {
+    this.workspace = workspace
+  }
+
+  /**
+   * Renders an element to an array of formatted lines.
+   *
+   * @remarks
+   * Abstract method that must be implemented by derived classes to
+   * convert specific element types into their multi-line representation.
+   *
+   * @param element - The element to render
+   * @param type - The rendering context type
+   * @returns Array of formatted output lines
+   */
+  abstract renderToLines(element: object, type: string): string[]
+}
+
+// ----------------------------------------------------------------------------

package/src/docusaurus/renderers/inctype.ts

@@ -0,0 +1,75 @@
+/*
+ * 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 util from 'node:util'
+
+import { ElementLinesRendererBase } from './element-renderer-base.js'
+import type { AbstractIncType } from '../../doxygen/data-model/compounds/inctype-dm.js'
+
+// ----------------------------------------------------------------------------
+
+/**
+ * Renderer for include directive elements in documentation.
+ *
+ * @remarks
+ * Handles the rendering of #include statements found in source code,
+ * converting them to appropriate HTML output with proper link generation
+ * when the included file is documented.
+ *
+ * @public
+ */
+export class IncTypeLinesRenderer extends ElementLinesRendererBase {
+  /**
+   * Renders an include element to formatted output lines.
+   *
+   * @remarks
+   * Converts Doxygen include elements into HTML format with appropriate
+   * angle brackets or quotes, and creates links to documented files
+   * when available. Handles both local includes (quotes) and system
+   * includes (angle brackets).
+   *
+   * @param element - The include element to render
+   * @param type - The rendering context type
+   * @returns Array of formatted output lines
+   */
+  override renderToLines(element: AbstractIncType, type: string): string[] {
+    // console.log(util.inspect(element, { compact: false, depth: 999 }))
+
+    const lines: string[] = []
+
+    let permalink: string | undefined = ''
+    if (element.refId !== undefined) {
+      permalink = this.workspace.getPagePermalink(element.refId)
+      // May be undefined.
+    }
+
+    const content = this.workspace.renderString(element.text.trim(), type)
+    let text = ''
+    text += '#include '
+    text += element.local ? '"' : '<'
+    if (permalink !== undefined && permalink.length > 0) {
+      text += `<a href="${permalink}">${content}</a>`
+    } else {
+      text += content
+    }
+    text += element.local ? '"' : '&gt;'
+    // text += '</code>'
+
+    lines.push(text)
+
+    return lines
+  }
+}
+
+// ----------------------------------------------------------------------------

package/src/docusaurus/renderers/linkedtexttype.ts

@@ -0,0 +1,64 @@
+/*
+ * 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 util from 'node:util'
+
+import { ElementStringRendererBase } from './element-renderer-base.js'
+import type { AbstractLinkedTextType } from '../../doxygen/data-model/compounds/linkedtexttype-dm.js'
+
+// ----------------------------------------------------------------------------
+
+// <xsd:complexType name="linkedTextType" mixed="true">   <-- Character data
+//                  is allowed to appear between the child elements!
+//   <xsd:sequence>
+//   <xsd:element name="ref" type="refTextType" minOccurs="0"
+//                                              maxOccurs="unbounded" />
+//   </xsd:sequence>
+// </xsd:complexType>
+
+/**
+ * Renderer for Doxygen linked text elements containing mixed content.
+ *
+ * @remarks
+ * Handles complex text structures that contain both character data and
+ * reference elements. Renders child elements recursively to build the
+ * complete text output with embedded links.
+ *
+ * @public
+ */
+export class LinkedTextTypeStringRenderer extends ElementStringRendererBase {
+  /**
+   * Renders a linked text element to a formatted string.
+   *
+   * @remarks
+   * Processes all child elements in sequence to generate the complete
+   * text output with embedded references and mixed content. Maintains
+   * the original order of text and reference elements.
+   *
+   * @param element - The linked text element to render
+   * @param type - The rendering context type
+   * @returns The formatted string with mixed content
+   */
+  renderToString(element: AbstractLinkedTextType, type: string): string {
+    // console.log(util.inspect(element, { compact: false, depth: 999 }))
+
+    let text = ''
+
+    text += this.workspace.renderElementsArrayToString(element.children, type)
+
+    return text
+  }
+}
+
+// ----------------------------------------------------------------------------