@xpack/doxygen2docusaurus 2.0.0 → 2.1.0

package/src/docusaurus/renderers/docinternalstype.ts

@@ -0,0 +1,354 @@
+/*
+ * 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 {
+  AbstractDocSect1Type,
+  AbstractDocSect2Type,
+  AbstractDocSect3Type,
+  AbstractDocSect4Type,
+  AbstractDocSect5Type,
+  AbstractDocSect6Type,
+} from '../../doxygen/data-model/compounds/descriptiontype-dm.js'
+import { getPermalinkAnchor } from '../utils.js'
+
+// ----------------------------------------------------------------------------
+
+// Sections are entered with @sect, @subsect, etc and in Docusaurus
+// start wih H2. The markdown syntax is used to make the titles appear
+// in the table of contents.
+
+/**
+ * Renderer for Doxygen level-1 section elements.
+ *
+ * @remarks
+ * Converts Doxygen section elements to Docusaurus markdown format.
+ * Generates H2 headings with optional anchor IDs for table of contents
+ * integration and cross-referencing within documentation.
+ *
+ * @public
+ */
+export class DocS1TypeLinesRenderer extends ElementLinesRendererBase {
+  /**
+   * Renders a level-1 section element to formatted output lines.
+   *
+   * @remarks
+   * Creates markdown H2 heading with optional anchor for the section title
+   * and renders child elements. Removes trailing periods from titles and
+   * includes anchor links when section IDs are available.
+   *
+   * @param element - The level-1 section element to render
+   * @param type - The rendering context type
+   * @returns Array of markdown lines for the section
+   */
+  override renderToLines(
+    element: AbstractDocSect1Type,
+    type: string
+  ): string[] {
+    // console.log(util.inspect(element, { compact: false, depth: 999 }))
+
+    const lines: string[] = []
+
+    const title = this.workspace
+      .renderElementToString(element.title, 'markdown')
+      .trim()
+      .replace(/\.$/, '')
+    if (title.length > 0) {
+      lines.push('')
+      if (element.id !== undefined) {
+        const anchor = getPermalinkAnchor(element.id)
+        lines.push(`## ${title} {#${anchor}}`)
+      } else {
+        lines.push(`## ${title}}`)
+      }
+    }
+
+    lines.push('')
+    lines.push(
+      ...this.workspace.renderElementsArrayToLines(element.children, type)
+    )
+
+    return lines
+  }
+}
+
+/**
+ * Renderer for Doxygen level-2 section elements.
+ *
+ * @remarks
+ * Converts Doxygen subsection elements to Docusaurus markdown format.
+ * Generates H3 headings with optional anchor IDs for hierarchical
+ * documentation structure and navigation support.
+ *
+ * @public
+ */
+export class DocS2TypeLinesRenderer extends ElementLinesRendererBase {
+  /**
+   * Renders a level-2 section element to formatted output lines.
+   *
+   * @remarks
+   * Creates markdown H3 heading with optional anchor for the subsection
+   * title and renders child elements. Maintains consistent formatting
+   * with parent section renderer patterns.
+   *
+   * @param element - The level-2 section element to render
+   * @param type - The rendering context type
+   * @returns Array of markdown lines for the subsection
+   */
+  override renderToLines(
+    element: AbstractDocSect2Type,
+    type: string
+  ): string[] {
+    // console.log(util.inspect(element, { compact: false, depth: 999 }))
+
+    const lines: string[] = []
+
+    const title = this.workspace
+      .renderElementToString(element.title, 'markdown')
+      .trim()
+      .replace(/\.$/, '')
+    if (title.length > 0) {
+      lines.push('')
+      if (element.id !== undefined) {
+        const anchor = getPermalinkAnchor(element.id)
+        lines.push(`### ${title} {#${anchor}}`)
+      } else {
+        lines.push(`### ${title}}`)
+      }
+    }
+    lines.push('')
+    lines.push(
+      ...this.workspace.renderElementsArrayToLines(element.children, type)
+    )
+
+    return lines
+  }
+}
+
+/**
+ * Renderer for Doxygen level-3 section elements.
+ *
+ * @remarks
+ * Converts Doxygen sub-subsection elements to Docusaurus markdown format.
+ * Generates H4 headings with optional anchor IDs for deep hierarchical
+ * documentation structure and comprehensive navigation.
+ *
+ * @public
+ */
+export class DocS3TypeLinesRenderer extends ElementLinesRendererBase {
+  /**
+   * Renders a level-3 section element to formatted output lines.
+   *
+   * @remarks
+   * Creates markdown H4 heading with optional anchor for the sub-subsection
+   * title and renders child elements. Follows established patterns for
+   * consistent documentation hierarchy.
+   *
+   * @param element - The level-3 section element to render
+   * @param type - The rendering context type
+   * @returns Array of markdown lines for the sub-subsection
+   */
+  override renderToLines(
+    element: AbstractDocSect3Type,
+    type: string
+  ): string[] {
+    // console.log(util.inspect(element, { compact: false, depth: 999 }))
+
+    const lines: string[] = []
+
+    const title = this.workspace
+      .renderElementToString(element.title, 'markdown')
+      .trim()
+      .replace(/\.$/, '')
+    if (title.length > 0) {
+      lines.push('')
+      if (element.id !== undefined) {
+        const anchor = getPermalinkAnchor(element.id)
+        lines.push(`#### ${title} {#${anchor}}`)
+      } else {
+        lines.push(`#### ${title}}`)
+      }
+    }
+    lines.push('')
+    lines.push(
+      ...this.workspace.renderElementsArrayToLines(element.children, type)
+    )
+
+    return lines
+  }
+}
+
+/**
+ * Renderer for Doxygen level-4 section elements.
+ *
+ * @remarks
+ * Converts deep Doxygen section elements to Docusaurus markdown format.
+ * Generates H5 headings with optional anchor IDs for detailed documentation
+ * hierarchies and fine-grained content organisation.
+ *
+ * @public
+ */
+export class DocS4TypeLinesRenderer extends ElementLinesRendererBase {
+  /**
+   * Renders a level-4 section element to formatted output lines.
+   *
+   * @remarks
+   * Creates markdown H5 heading with optional anchor for deep section
+   * titles and renders child elements. Maintains hierarchy consistency
+   * for complex documentation structures.
+   *
+   * @param element - The level-4 section element to render
+   * @param type - The rendering context type
+   * @returns Array of markdown lines for the deep section
+   */
+  override renderToLines(
+    element: AbstractDocSect4Type,
+    type: string
+  ): string[] {
+    // console.log(util.inspect(element, { compact: false, depth: 999 }))
+
+    const lines: string[] = []
+
+    const title = this.workspace
+      .renderElementToString(element.title, 'markdown')
+      .trim()
+      .replace(/\.$/, '')
+    if (title.length > 0) {
+      lines.push('')
+      if (element.id !== undefined) {
+        const anchor = getPermalinkAnchor(element.id)
+        lines.push(`##### ${title} {#${anchor}}`)
+      } else {
+        lines.push(`##### ${title}}`)
+      }
+    }
+    lines.push('')
+    lines.push(
+      ...this.workspace.renderElementsArrayToLines(element.children, type)
+    )
+
+    return lines
+  }
+}
+
+/**
+ * Renderer for Doxygen level-5 section elements.
+ *
+ * @remarks
+ * Converts very deep Doxygen section elements to Docusaurus markdown format.
+ * Generates H6 headings with optional anchor IDs for extremely detailed
+ * documentation hierarchies and comprehensive content structuring.
+ *
+ * @public
+ */
+export class DocS5TypeLinesRenderer extends ElementLinesRendererBase {
+  /**
+   * Renders a level-5 section element to formatted output lines.
+   *
+   * @remarks
+   * Creates markdown H6 heading with optional anchor for very deep section
+   * titles and renders child elements. Supports maximum depth documentation
+   * organisation for complex technical content.
+   *
+   * @param element - The level-5 section element to render
+   * @param type - The rendering context type
+   * @returns Array of markdown lines for the very deep section
+   */
+  override renderToLines(
+    element: AbstractDocSect5Type,
+    type: string
+  ): string[] {
+    // console.log(util.inspect(element, { compact: false, depth: 999 }))
+
+    const lines: string[] = []
+
+    const title = this.workspace
+      .renderElementToString(element.title, 'markdown')
+      .trim()
+      .replace(/\.$/, '')
+    if (title.length > 0) {
+      lines.push('')
+      if (element.id !== undefined) {
+        const anchor = getPermalinkAnchor(element.id)
+        lines.push(`###### ${title} {#${anchor}}`)
+      } else {
+        lines.push(`###### ${title}}`)
+      }
+    }
+    lines.push('')
+    lines.push(
+      ...this.workspace.renderElementsArrayToLines(element.children, type)
+    )
+
+    return lines
+  }
+}
+
+/**
+ * Renderer for Doxygen level-6 section elements.
+ *
+ * @remarks
+ * Converts the deepest Doxygen section elements to Docusaurus format.
+ * Uses bold text formatting instead of headers due to markdown limitations
+ * at this depth level while maintaining anchor functionality.
+ *
+ * @public
+ */
+export class DocS6TypeLinesRenderer extends ElementLinesRendererBase {
+  /**
+   * Renders a level-6 section element to formatted output lines.
+   *
+   * @remarks
+   * Creates bold text with optional anchor for maximum depth sections
+   * and renders child elements. Uses alternative formatting since
+   * markdown heading levels are exhausted at this depth.
+   *
+   * @param element - The level-6 section element to render
+   * @param type - The rendering context type
+   * @returns Array of formatted lines for the deepest section
+   */
+  override renderToLines(
+    element: AbstractDocSect6Type,
+    type: string
+  ): string[] {
+    // console.log(util.inspect(element, { compact: false, depth: 999 }))
+
+    const lines: string[] = []
+
+    const title = this.workspace
+      .renderElementToString(element.title, 'markdown')
+      .trim()
+      .replace(/\.$/, '')
+    if (title.length > 0) {
+      lines.push('')
+      if (element.id !== undefined) {
+        const anchor = getPermalinkAnchor(element.id)
+        lines.push(`####### ${title} {#${anchor}}`)
+      } else {
+        lines.push(`####### ${title}}`)
+      }
+    }
+
+    lines.push('')
+    lines.push(
+      ...this.workspace.renderElementsArrayToLines(element.children, type)
+    )
+
+    return lines
+  }
+}
+
+// ----------------------------------------------------------------------------

package/src/docusaurus/renderers/doclisttype.ts

@@ -0,0 +1,134 @@
+/*
+ * 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 AbstractDocListType,
+  ItemizedListDataModel,
+  OrderedListDataModel,
+} from '../../doxygen/data-model/compounds/descriptiontype-dm.js'
+
+// ----------------------------------------------------------------------------
+
+/**
+ * Renderer for list type elements in documentation.
+ *
+ * @remarks
+ * Handles the rendering of both ordered and unordered lists as parsed from
+ * Doxygen XML, converting them into appropriate HTML markup with proper
+ * styling classes and list type attributes.
+ *
+ * @public
+ */
+export class DocListTypeLinesRenderer extends ElementLinesRendererBase {
+  /**
+   * Renders a list element to formatted output lines.
+   *
+   * @remarks
+   * Converts Doxygen list elements into HTML lists (ul/ol) with appropriate
+   * CSS classes and type attributes. Handles both itemised (unordered) and
+   * ordered lists, including special check-style formatting when needed.
+   *
+   * @param element - The list element to render
+   * @param type - The rendering context type
+   * @returns Array of formatted output lines
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  override renderToLines(element: AbstractDocListType, type: string): string[] {
+    // console.log(util.inspect(element, { compact: false, depth: 999 }))
+    // console.log(element)
+
+    let classCheck = ''
+    for (const listItem of element.listItems) {
+      if (listItem.override !== undefined) {
+        classCheck = ' check'
+        break
+      }
+    }
+
+    const lines: string[] = []
+
+    lines.push('')
+    if (element instanceof ItemizedListDataModel) {
+      lines.push(`<ul class="doxyList ${classCheck}">`)
+    } else if (element instanceof OrderedListDataModel) {
+      if (element.type.length > 0) {
+        lines.push(`<ol class="doxyList" type="${element.type}">`)
+      } else {
+        lines.push('<ol class="doxyList" type="1">')
+      }
+    }
+
+    for (const listItem of element.listItems) {
+      let classChecked = ''
+      if (listItem.override !== undefined) {
+        classChecked = ` class="${listItem.override}"`
+      }
+
+      if (listItem.paras !== undefined) {
+        // console.log(listItem.paras)
+        this.workspace.skipElementsPara(listItem.paras)
+
+        if (listItem.paras.length > 0) {
+          let text = ''
+          text += `<li${classChecked}>`
+
+          const paraLines: string[] = []
+          for (const para of listItem.paras) {
+            paraLines.push(
+              this.workspace.renderElementToString(para, 'html').trim()
+            )
+          }
+          // Two \n to separate paragraphs when there is no <p>.
+          text += paraLines.join('\n\n')
+          text += '</li>'
+          lines.push(text)
+        }
+      }
+      if (listItem.value !== undefined) {
+        if (this.workspace.options.verbose) {
+          console.warn(
+            'Value',
+            listItem.value,
+            'ignored in',
+            this.constructor.name
+          )
+        }
+      }
+    }
+
+    if (element instanceof ItemizedListDataModel) {
+      lines.push('</ul>')
+    } else if (element instanceof OrderedListDataModel) {
+      lines.push('</ol>')
+    }
+
+    if (element.start !== undefined) {
+      if (this.workspace.options.verbose) {
+        console.warn(
+          'Start',
+          element.start,
+          'ignored in',
+          this.constructor.name
+        )
+      }
+    }
+
+    return lines
+  }
+}
+
+// ----------------------------------------------------------------------------

package/src/docusaurus/renderers/doctabletype.ts

@@ -0,0 +1,220 @@
+/*
+ * 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,
+  ElementStringRendererBase,
+} from './element-renderer-base.js'
+import type {
+  AbstractDocCaptionType,
+  AbstractDocEntryType,
+  AbstractDocRowType,
+  AbstractDocTableType,
+} from '../../doxygen/data-model/compounds/descriptiontype-dm.js'
+
+// ----------------------------------------------------------------------------
+
+/**
+ * Renderer for Doxygen document table elements.
+ *
+ * @remarks
+ * Converts Doxygen table structures to HTML table format with optional
+ * captions. Processes table rows and maintains styling through CSS
+ * classes for consistent documentation presentation.
+ *
+ * @public
+ */
+export class DocTableTypeLinesRenderer extends ElementLinesRendererBase {
+  /**
+   * Renders a document table element to formatted output lines.
+   *
+   * @remarks
+   * Creates HTML table structure with optional caption and processes
+   * all table rows. Applies CSS classes for styling and maintains
+   * proper table markup for documentation display.
+   *
+   * @param element - The document table element to render
+   * @param type - The rendering context type (unused in implementation)
+   * @returns Array of HTML strings forming the table structure
+   */
+  override renderToLines(
+    element: AbstractDocTableType,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    type: string
+  ): string[] {
+    // console.log(util.inspect(element, { compact: false, depth: 999 }))
+
+    const lines: string[] = []
+
+    lines.push('')
+    lines.push('<table class="doxyTable">')
+    if (element.caption !== undefined) {
+      lines.push(this.workspace.renderElementToString(element.caption, 'html'))
+    }
+    lines.push(
+      ...this.workspace.renderElementsArrayToLines(element.rows, 'html')
+    )
+    lines.push('</table>')
+
+    return lines
+  }
+}
+
+/**
+ * Renderer for Doxygen document table caption elements.
+ *
+ * @remarks
+ * Generates HTML caption elements for table titles and descriptions.
+ * Processes caption content to provide contextual information about
+ * table contents and purpose within documentation.
+ *
+ * @public
+ */
+export class DocCaptionLinesRenderer extends ElementLinesRendererBase {
+  /**
+   * Renders a document caption element to formatted output lines.
+   *
+   * @remarks
+   * Creates HTML caption element containing the processed caption content.
+   * Renders child elements to build complete caption text with proper
+   * markup and formatting preservation.
+   *
+   * @param element - The document caption element to render
+   * @param type - The rendering context type (unused in implementation)
+   * @returns Array containing the HTML caption element
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  renderToLines(element: AbstractDocCaptionType, type: string): string[] {
+    // console.log(util.inspect(element, { compact: false, depth: 999 }))
+
+    let text = ''
+
+    let attributes = ''
+    if (element.id.length > 0) {
+      attributes += ` id="${element.id}"`
+    }
+    text += `<caption${attributes}>`
+    text += this.workspace
+      .renderElementsArrayToString(element.children, 'html')
+      .trim()
+    text += '</caption>'
+
+    return [text]
+  }
+}
+
+/**
+ * Renderer for Doxygen document table row elements.
+ *
+ * @remarks
+ * Generates HTML table row structure containing table entries.
+ * Processes all entry elements within the row to build complete
+ * table row markup for documentation display.
+ *
+ * @public
+ */
+export class DocRowTypeLinesRenderer extends ElementLinesRendererBase {
+  /**
+   * Renders a document table row element to formatted output lines.
+   *
+   * @remarks
+   * Creates HTML table row tags around rendered table entries.
+   * Processes entry elements to generate the complete row structure
+   * with proper table markup.
+   *
+   * @param element - The document table row element to render
+   * @param type - The rendering context type (unused in implementation)
+   * @returns Array of HTML strings forming the table row
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  override renderToLines(element: AbstractDocRowType, type: string): string[] {
+    // console.log(util.inspect(element, { compact: false, depth: 999 }))
+
+    const lines: string[] = []
+
+    lines.push('<tr>')
+    lines.push(
+      ...this.workspace.renderElementsArrayToLines(element.entries, 'html')
+    )
+    lines.push('</tr>')
+
+    return lines
+  }
+}
+
+/**
+ * Renderer for Doxygen document table entry elements.
+ *
+ * @remarks
+ * Converts table cell elements to HTML table data or header cells
+ * with appropriate attributes. Handles cell spanning, alignment,
+ * and styling attributes for flexible table presentation.
+ *
+ * @public
+ */
+export class DocEntryTypeStringRenderer extends ElementStringRendererBase {
+  /**
+   * Renders a document table entry element to a formatted string.
+   *
+   * @remarks
+   * Creates HTML table cell (td or th) with attributes including
+   * colspan, rowspan, alignment, and styling. Processes cell content
+   * and applies appropriate markup based on header status.
+   *
+   * @param element - The document table entry element to render
+   * @param type - The rendering context type (unused in implementation)
+   * @returns The formatted HTML table cell string
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  renderToString(element: AbstractDocEntryType, type: string): string {
+    // console.log(util.inspect(element, { compact: false, depth: 999 }))
+
+    let text = ''
+
+    let attributes = ''
+    if (element.colspan !== undefined) {
+      attributes += ` colspan="${element.colspan.toString()}"`
+    }
+    if (element.rowspan !== undefined) {
+      attributes += ` rowspan="${element.rowspan.toString()}"`
+    }
+    if (element.align !== undefined) {
+      attributes += ` align="${element.align}"`
+    }
+    if (element.valign !== undefined) {
+      attributes += ` valign="${element.valign}"`
+    }
+    if (element.width !== undefined) {
+      attributes += ` width="${element.width}"`
+    }
+    if (element.classs !== undefined) {
+      attributes += ` class="${element.classs}"`
+    }
+
+    this.workspace.skipElementsPara(element.paras)
+    const entry = this.workspace
+      .renderElementsArrayToString(element.paras, 'html')
+      .trim()
+    if (element.thead) {
+      text += `<th${attributes}>${entry}</th>`
+    } else {
+      text += `<td${attributes}>${entry}</td>`
+    }
+    return text
+  }
+}
+
+// ----------------------------------------------------------------------------