@xpack/doxygen2docusaurus 1.1.0 → 2.1.0

package/src/docusaurus/renderers/listingtype.ts

@@ -0,0 +1,235 @@
+/*
+ * 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 util from 'node:util'
+
+import {
+  type AbstractCodeLineType,
+  CodeLineDataModel,
+  type AbstractHighlightType,
+  HighlightDataModel,
+  type AbstractListingTypeBase,
+  MemberProgramListingDataModel,
+} from '../../doxygen/data-model/compounds/descriptiontype-dm.js'
+import { ElementLinesRendererBase } from './element-renderer-base.js'
+import type { Workspace } from '../workspace.js'
+
+// ----------------------------------------------------------------------------
+
+/**
+ * Renderer for program listing elements in documentation.
+ *
+ * @remarks
+ * Handles the rendering of source code listings as parsed from Doxygen XML,
+ * converting them into formatted HTML output with syntax highlighting and
+ * line numbering. Supports both full program listings and member-specific
+ * code segments.
+ *
+ * @public
+ */
+export class ListingTypeLinesRenderer extends ElementLinesRendererBase {
+  /**
+   * Renders a program listing element to formatted output lines.
+   *
+   * @remarks
+   * Converts Doxygen program listing elements into HTML with appropriate
+   * CSS classes, line numbers, and syntax highlighting. Handles anchor
+   * generation for navigation and cross-referencing.
+   *
+   * @param element - The listing element to render
+   * @param type - The rendering context type
+   * @returns Array of formatted output lines
+   */
+  override renderToLines(
+    element: AbstractListingTypeBase,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    type: string
+  ): string[] {
+    // console.log(util.inspect(element, { compact: false, depth: 999 }))
+
+    if (element.codelines === undefined) {
+      return []
+    }
+
+    let showAnchor = true
+    if (element instanceof MemberProgramListingDataModel) {
+      showAnchor = false
+    }
+
+    const lines: string[] = []
+
+    lines.push('')
+    lines.push('<div class="doxyProgramListing">')
+
+    lines.push('')
+    for (const codeline of element.codelines) {
+      // Explicit type, since it may come from a markdown environment,
+      // like in the Doxygen docblocks page.
+      lines.push(
+        renderCodeLinesToString(this.workspace, codeline, 'html', showAnchor)
+      )
+    }
+
+    lines.push('')
+    lines.push('</div>')
+    lines.push('')
+
+    return lines
+  }
+}
+
+/**
+ * Renders individual code lines with syntax highlighting and line numbers.
+ *
+ * @remarks
+ * Converts a single code line element into HTML format with appropriate
+ * line numbering, anchors for navigation, and syntax highlighting support.
+ * Handles permalink generation for cross-references when available.
+ *
+ * @param workspace - The workspace instance for rendering utilities
+ * @param element - The code line element to render
+ * @param type - The rendering context type
+ * @param showAnchor - Whether to include anchor elements for navigation
+ * @returns Formatted HTML string for the code line
+ */
+function renderCodeLinesToString(
+  workspace: Workspace,
+  element: AbstractCodeLineType,
+  type: string,
+  showAnchor: boolean
+): string {
+  // console.log(util.inspect(element, { compact: false, depth: 999 }))
+  assert(element instanceof CodeLineDataModel)
+
+  if (element.external !== undefined) {
+    console.error('external ignored in', element.constructor.name)
+  }
+
+  let permalink: string | undefined = undefined
+  if (element.refid !== undefined && element.refkind !== undefined) {
+    permalink = workspace.getPermalink({
+      refid: element.refid,
+      kindref: element.refkind,
+    })
+  }
+
+  let text = ''
+
+  text += '<div class="doxyCodeLine">'
+  if (element.lineno !== undefined) {
+    text += '<span class="doxyLineNumber">'
+    const anchor = `l${element.lineno.toString().padStart(5, '0')}`
+    if (showAnchor) {
+      text += `<a id="${anchor}"></a>`
+    }
+    if (permalink !== undefined) {
+      text += `<a href="${permalink}">${element.lineno.toString()}</a>`
+    } else {
+      text += element.lineno.toString()
+    }
+    text += '</span>'
+  } else {
+    text += '<span class="doxyNoLineNumber">&nbsp;</span>'
+  }
+
+  const content = workspace.renderElementsArrayToString(
+    element.highlights,
+    type
+  )
+  if (content.length > 0) {
+    text += `<span class="doxyLineContent">${content}</span>`
+  }
+  text += '</div>'
+
+  return text
+}
+
+/**
+ * Renderer for syntax highlighting elements in code listings.
+ *
+ * @remarks
+ * Handles the rendering of syntax-highlighted code segments by converting
+ * Doxygen highlight elements into HTML spans with appropriate CSS classes.
+ * Optimised for direct HTML generation to improve build performance.
+ *
+ * @public
+ */
+export class HighlightTypeLinesRenderer extends ElementLinesRendererBase {
+  /**
+   * Mapping of Doxygen highlight classes to CSS class names.
+   *
+   * @remarks
+   * Maps Doxygen's built-in highlight types to corresponding CSS classes
+   * for consistent syntax highlighting across different code elements.
+   */
+  knownClasses: Record<string, string> = {
+    normal: 'doxyHighlight',
+    charliteral: 'doxyHighlightCharLiteral',
+    comment: 'doxyHighlightComment',
+    preprocessor: 'doxyHighlightPreprocessor',
+    keyword: 'doxyHighlightKeyword',
+    keywordtype: 'doxyHighlightKeywordType',
+    keywordflow: 'doxyHighlightKeywordFlow',
+    token: 'doxyHighlightToken',
+    stringliteral: 'doxyHighlightStringLiteral',
+    vhdlchar: 'doxyHighlightVhdlChar',
+    vhdlkeyword: 'doxyHighlightVhdlKeyword',
+    vhdllogic: 'doxyHighlightVhdlLogic',
+  }
+
+  /**
+   * Renders a syntax highlight element to formatted output lines.
+   *
+   * @remarks
+   * Converts Doxygen highlight elements into HTML span elements with
+   * appropriate CSS classes for syntax highlighting. Handles unknown
+   * highlight types by falling back to a default class.
+   *
+   * @param element - The highlight element to render
+   * @param type - The rendering context type
+   * @returns Array containing the formatted HTML span
+   */
+  override renderToLines(
+    element: AbstractHighlightType,
+    type: string
+  ): string[] {
+    // console.log(util.inspect(element, { compact: false, depth: 999 }))
+    assert(element instanceof HighlightDataModel)
+
+    let spanClass = this.knownClasses[element.classs]
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    if (spanClass === undefined) {
+      console.error(util.inspect(element, { compact: false, depth: 999 }))
+      console.error(
+        element.classs,
+        'not implemented yet in',
+        this.constructor.name
+      )
+      spanClass = 'doxyHighlight'
+    }
+
+    let text = ''
+
+    assert(element.children !== undefined)
+    if (element.children.length > 0) {
+      text += `<span class="${spanClass}">`
+      text += this.workspace.renderElementsArrayToString(element.children, type)
+      text += '</span>'
+    }
+
+    return [text]
+  }
+}
+
+// ----------------------------------------------------------------------------

package/src/docusaurus/renderers/paramtype.ts

@@ -0,0 +1,116 @@
+/*
+ * 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 { AbstractParamType } from '../../doxygen/data-model/compounds/paramtype-dm.js'
+
+// ----------------------------------------------------------------------------
+
+// <xsd:complexType name="paramType">
+//   <xsd:sequence>
+//     <xsd:element name="attributes" type="xsd:string" minOccurs="0" />
+//     <xsd:element name="type" type="linkedTextType" minOccurs="0" />
+//     <xsd:element name="declname" type="xsd:string" minOccurs="0" />
+//     <xsd:element name="defname" type="xsd:string" minOccurs="0" />
+//     <xsd:element name="array" type="xsd:string" minOccurs="0" />
+//     <xsd:element name="defval" type="linkedTextType" minOccurs="0" />
+//     <xsd:element name="typeconstraint" type="linkedTextType" minOccurs="0" />
+//     <xsd:element name="briefdescription" type="descriptionType"
+//        minOccurs="0" />
+//   </xsd:sequence>
+// </xsd:complexType>
+
+/**
+ * Renderer for parameter type elements in function documentation.
+ *
+ * @remarks
+ * Handles the rendering of function and method parameters as parsed from
+ * Doxygen XML, converting them into formatted output that includes type
+ * information, parameter names, and default values when available.
+ *
+ * @public
+ */
+export class ParamTypeLinesRenderer extends ElementLinesRendererBase {
+  /**
+   * Renders a parameter element to formatted output lines.
+   *
+   * @remarks
+   * Converts Doxygen parameter elements into formatted text including
+   * type information, parameter names, array specifications, and default
+   * values. Handles both declaration and definition name variants.
+   *
+   * @param element - The parameter element to render
+   * @param type - The rendering context type
+   * @returns Array of formatted output lines
+   */
+  override renderToLines(element: AbstractParamType, type: string): string[] {
+    // console.log(util.inspect(element, { compact: false, depth: 999 }))
+
+    if (element.attributes !== undefined) {
+      console.error(util.inspect(element, { compact: false, depth: 999 }))
+      console.error(
+        element.elementName,
+        'property attributes not yet rendered in',
+        this.constructor.name
+      )
+    }
+    if (element.defname !== undefined) {
+      console.error(util.inspect(element, { compact: false, depth: 999 }))
+      console.error(
+        element.elementName,
+        'property defname not yet rendered in',
+        this.constructor.name
+      )
+    }
+    if (element.typeconstraint !== undefined) {
+      console.error(util.inspect(element, { compact: false, depth: 999 }))
+      console.error(
+        element.elementName,
+        'property typeconstraint not yet rendered in',
+        this.constructor.name
+      )
+    }
+    if (element.briefdescription !== undefined) {
+      console.error(util.inspect(element, { compact: false, depth: 999 }))
+      console.error(
+        element.elementName,
+        'property briefdescription not yet rendered in',
+        this.constructor.name
+      )
+    }
+
+    let text = ''
+
+    text += this.workspace.renderElementToString(element.type, type)
+    if (element.declname !== undefined) {
+      text += ` ${element.declname}`
+      if (element.array !== undefined) {
+        text += `=${element.array}`
+      }
+      if (element.defval !== undefined) {
+        const defvalStr = this.workspace.renderElementToString(
+          element.defval,
+          type
+        )
+        text += `=${defvalStr}`
+      }
+    }
+
+    return [text]
+  }
+}
+
+// ----------------------------------------------------------------------------

package/src/docusaurus/renderers/referencetype.ts

@@ -0,0 +1,83 @@
+/*
+ * 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 AbstractReferenceType,
+  ReferenceDataModel,
+  ReferencedByDataModel,
+} from '../../doxygen/data-model/compounds/referencetype-dm.js'
+import { sanitizeAnonymousNamespace } from '../utils.js'
+
+// ----------------------------------------------------------------------------
+
+/**
+ * Renderer for reference elements in documentation cross-references.
+ *
+ * @remarks
+ * Handles the rendering of cross-reference elements that link to other
+ * documented members, creating appropriate hyperlinks with proper
+ * permalinks for navigation within the documentation.
+ *
+ * @public
+ */
+export class ReferenceTypeStringRenderer extends ElementStringRendererBase {
+  /**
+   * Renders a reference element to a formatted string with hyperlinks.
+   *
+   * @remarks
+   * Converts Doxygen reference elements into HTML anchor tags with
+   * appropriate permalinks to the referenced members. Handles both
+   * forward references and reverse references whilst sanitising
+   * anonymous namespace names for display.
+   *
+   * @param element - The reference element to render
+   * @param type - The rendering context type
+   * @returns Formatted HTML string with hyperlink
+   */
+  renderToString(element: AbstractReferenceType, type: string): string {
+    // console.log(util.inspect(element, { compact: false, depth: 999 }))
+
+    let text = ''
+
+    if (
+      element instanceof ReferencedByDataModel ||
+      element instanceof ReferenceDataModel
+    ) {
+      const memberPermalink = this.workspace.getPermalink({
+        refid: element.refid,
+        kindref: 'member',
+      })
+      assert(memberPermalink !== undefined)
+      const name = this.workspace.renderString(
+        sanitizeAnonymousNamespace(element.text.trim()),
+        type
+      )
+      text += `<a href="${memberPermalink}">${name}</a>`
+    } else {
+      console.error(
+        element.constructor.name,
+        'not implemented by',
+        this.constructor.name
+      )
+      return ''
+    }
+
+    return text
+  }
+}
+
+// ----------------------------------------------------------------------------

package/src/docusaurus/renderers/reftexttype.ts

@@ -0,0 +1,81 @@
+/*
+ * 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 { AbstractRefTextType } from '../../doxygen/data-model/compounds/reftexttype-dm.js'
+
+// ----------------------------------------------------------------------------
+
+/**
+ * Renderer for Doxygen reference text elements with linking functionality.
+ *
+ * @remarks
+ * Converts reference text elements into HTML anchor tags when a valid
+ * permalink is available, otherwise renders as plain text. Provides
+ * cross-reference functionality for Doxygen elements.
+ *
+ * @public
+ */
+export class RefTextTypeStringRenderer extends ElementStringRendererBase {
+  /**
+   * Renders a reference text element to a formatted string with linking.
+   *
+   * @remarks
+   * Generates an HTML anchor tag when a valid permalink exists for the
+   * referenced element, otherwise renders the text content directly.
+   * Logs warnings for unsupported attributes that are not yet implemented.
+   *
+   * @param element - The reference text element to render
+   * @param type - The rendering context type
+   * @returns The formatted HTML string with optional link
+   */
+  renderToString(element: AbstractRefTextType, type: string): string {
+    // console.log(util.inspect(element, { compact: false, depth: 999 }))
+
+    if (element.external !== undefined) {
+      console.error(
+        element.elementName,
+        'attribute external not yet rendered in',
+        this.constructor.name
+      )
+    }
+    if (element.tooltip !== undefined) {
+      console.error(
+        element.elementName,
+        'attribute tooltip not yet rendered in',
+        this.constructor.name
+      )
+    }
+
+    let text = ''
+
+    const permalink = this.workspace.getPermalink({
+      refid: element.refid,
+      kindref: element.kindref,
+    })
+
+    const content = this.workspace.renderString(element.text.trim(), type)
+    if (permalink !== undefined && permalink.length > 0) {
+      text += `<a href="${permalink}">${content}</a>`
+    } else {
+      text += content
+    }
+
+    return text
+  }
+}
+
+// ----------------------------------------------------------------------------

package/src/docusaurus/renderers/reftype.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 { AbstractRefType } from '../../doxygen/data-model/compounds/reftype-dm.js'
+
+// ----------------------------------------------------------------------------
+
+/**
+ * Renderer for reference type elements in documentation cross-references.
+ *
+ * @remarks
+ * Handles the rendering of reference elements that link to other documented
+ * entities, creating appropriate hyperlinks with permalinks when targets
+ * are available. Used for cross-referencing between documentation elements.
+ *
+ * @public
+ */
+export class RefTypeLinesRenderer extends ElementLinesRendererBase {
+  /**
+   * Renders a reference element to formatted output lines.
+   *
+   * @remarks
+   * Converts Doxygen reference elements into HTML anchor tags with
+   * appropriate permalinks to the referenced entities. Falls back to
+   * plain text when no permalink is available for the target.
+   *
+   * @param element - The reference element to render
+   * @param type - The rendering context type
+   * @returns Array of formatted output lines
+   */
+  override renderToLines(element: AbstractRefType, type: string): string[] {
+    // console.log(util.inspect(element, { compact: false, depth: 999 }))
+
+    if (element.prot !== undefined) {
+      console.error(
+        element.elementName,
+        'attribute prot not yet rendered in',
+        this.constructor.name
+      )
+    }
+    if (element.inline !== undefined) {
+      console.error(
+        element.elementName,
+        'attribute inline not yet rendered in',
+        this.constructor.name
+      )
+    }
+
+    const lines: string[] = []
+
+    const content = this.workspace.renderString(element.text.trim(), type)
+    const permalink = this.workspace.getPagePermalink(element.refid)
+    if (permalink !== undefined && permalink.length > 0) {
+      lines.push(`<a href="${permalink}">${content}</a>`)
+    } else {
+      lines.push(content)
+    }
+
+    return lines
+  }
+}
+
+// ----------------------------------------------------------------------------