@xpack/doxygen2docusaurus 2.0.0 → 2.1.0

package/src/docusaurus/view-model/compound-base-vm.ts

@@ -0,0 +1,1340 @@
+/*
+ * 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 * as util from 'node:util'
+import assert from 'node:assert'
+import path from 'node:path'
+
+import type { FrontMatter } from '../types.js'
+import { ParaDataModel } from '../../doxygen/data-model/compounds/descriptiontype-dm.js'
+import type { CollectionBase } from './collection-base.js'
+import type { AbstractRefType } from '../../doxygen/data-model/compounds/reftype-dm.js'
+import { joinWithLast, sanitizeAnonymousNamespace } from '../utils.js'
+import { Section } from './members-vm.js'
+import type { TemplateParamListDataModel } from '../../doxygen/data-model/compounds/templateparamlisttype-dm.js'
+import { RefTextDataModel } from '../../doxygen/data-model/compounds/reftexttype-dm.js'
+import type { DefValDataModel } from '../../doxygen/data-model/compounds/linkedtexttype-dm.js'
+import type { LocationDataModel } from '../../doxygen/data-model/compounds/locationtype-dm.js'
+import type { CompoundDefDataModel } from '../../doxygen/data-model/compounds/compounddef-dm.js'
+import type { IncludesDataModel } from '../../doxygen/data-model/compounds/inctype-dm.js'
+import {
+  SectionDefByKindDataModel,
+  type SectionDefDataModel,
+} from '../../doxygen/data-model/compounds/sectiondeftype-dm.js'
+import type { AbstractMemberBaseType } from '../../doxygen/data-model/compounds/memberdeftype-dm.js'
+import type {
+  ReferenceDataModel,
+  ReferencedByDataModel,
+} from '../../doxygen/data-model/compounds/referencetype-dm.js'
+import { Concept } from './concepts-vm.js'
+
+// ----------------------------------------------------------------------------
+
+/**
+ * Abstract base class for all compound documentation objects.
+ *
+ * The CompoundBase class provides common functionality and structure for
+ * all types of documentation compounds (classes, files, namespaces, etc.),
+ * including rendering, navigation, and metadata management.
+ *
+ * @public
+ */
+export abstract class CompoundBase {
+  /** The Doxygen compound kind (class, file, namespace, etc.). */
+  kind = ''
+
+  /** The display name of the compound. */
+  compoundName = ''
+
+  /** Unique identifier for the compound. */
+  id = ''
+
+  /** The collection this compound belongs to. */
+  collection: CollectionBase
+
+  /** HTML-rendered title string for display purposes. */
+  titleHtmlString: string | undefined
+
+  /** File path where the compound is located in the source. */
+  locationFilePath: string | undefined
+
+  // --------------------------------------------------------------------------
+
+  /** Parent compound in the hierarchy (not used for classes). */
+  parent?: CompoundBase
+
+  /**
+   * Array of child compound identifiers for two-step initialisation.
+   *
+   * Set in 2 steps, first the Ids and then, when all objects are in,
+   * the references.
+   * Folder objects use separate arrays for files and folders children.
+   */
+  childrenIds: string[] = []
+
+  /** Array of resolved child compound instances. */
+  children: CompoundBase[] = []
+
+  /**
+   * Short name for sidebar display within limited space.
+   * If undefined, the compound is excluded from the sidebar.
+   */
+  sidebarLabel: string | undefined
+
+  /**
+   * Relative path to the output folder starting with plural kind.
+   * If undefined, the compound is excluded from the sidebar.
+   */
+  sidebarId: string | undefined
+
+  /**
+   * Relative permalink below outputFolderPath without leading slash.
+   * If undefined, no Markdown file is generated for the compound.
+   */
+  relativePermalink: string | undefined
+
+  /** The name shown in the index section. */
+  indexName = ''
+
+  /** The name used in tree entries for top-level index pages. */
+  treeEntryName = ''
+
+  /** The name shown in the page title. */
+  pageTitle = ''
+
+  /** HTML-rendered brief description for display purposes. */
+  briefDescriptionHtmlString: string | undefined
+  /** HTML-rendered detailed description lines for full documentation. */
+  detailedDescriptionHtmlLines: string[] | undefined
+
+  /** Flag indicating if detailed description contains sect1 elements. */
+  hasSect1InDescription = false
+
+  /** Location information lines for rendering file/line references. */
+  locationLines: string[] | undefined
+
+  /** Array of member sections organised by type and visibility. */
+  sections: Section[] = []
+
+  /** Set of unique file locations for this compound. */
+  locationSet = new Set<string>()
+
+  /** Array of include directives for this compound. */
+  includes: IncludesDataModel[] | undefined
+
+  /** Map of inner compounds organised by type. */
+  innerCompounds: Map<string, CompoundDefDataModel> | undefined
+
+  /** Private data storage for internal compound definition reference. */
+  _private: {
+    /** Reference to the source data model object. */
+    _compoundDef?: CompoundDefDataModel | undefined
+  } = {}
+
+  // --------------------------------------------------------------------------
+
+  /**
+   * Creates a new compound base instance from definition data.
+   *
+   * @remarks
+   * Initialises the basic compound properties including kind, name,
+   * identifier, and optional title and location information. Sets up
+   * the collection reference and processes HTML rendering for titles.
+   *
+   * @param collection - The parent collection managing this compound
+   * @param compoundDef - The Doxygen compound definition containing source data
+   */
+  constructor(collection: CollectionBase, compoundDef: CompoundDefDataModel) {
+    this._private._compoundDef = compoundDef
+
+    this.collection = collection
+
+    const { kind, compoundName, id } = compoundDef
+    this.kind = kind
+    this.compoundName = sanitizeAnonymousNamespace(compoundName)
+    this.id = id
+
+    if (compoundDef.title !== undefined) {
+      this.titleHtmlString = this.collection.workspace.renderString(
+        compoundDef.title,
+        'html'
+      )
+    }
+
+    if (compoundDef.location?.file !== undefined) {
+      const { file } = compoundDef.location
+      this.locationFilePath = file
+    }
+  }
+
+  /**
+   * Creates and organises member sections for the compound.
+   *
+   * @remarks
+   * Processes section definitions from the compound data model,
+   * reorders them by type and visibility, and creates Section
+   * instances for rendering. Sorts sections according to their
+   * logical display order.
+   *
+   * @param classUnqualifiedName - Optional class name for special method
+   *   detection
+   */
+  createSections(classUnqualifiedName?: string): void {
+    const reorderedSectionDefs = this.reorderSectionDefs(classUnqualifiedName)
+
+    if (reorderedSectionDefs !== undefined) {
+      const sections: Section[] = []
+      for (const sectionDef of reorderedSectionDefs) {
+        sections.push(new Section(this, sectionDef))
+      }
+      this.sections = sections.sort(
+        (a, b) => a.getSectionOrderByKind() - b.getSectionOrderByKind()
+      )
+    }
+  }
+
+  /**
+   * Reorders section definitions by member type and adjusts section kinds.
+   *
+   * @remarks
+   * Processes member definitions and groups them by adjusted section
+   * kinds, handling user-defined sections separately. Creates new
+   * section definitions organised by member types for consistent
+   * display ordering.
+   *
+   * @param classUnqualifiedName - Optional class name for special method
+   *   detection
+   * @returns Array of reordered section definitions or undefined if none exist
+   */
+  private reorderSectionDefs(
+    classUnqualifiedName?: string
+  ): SectionDefDataModel[] | undefined {
+    const sectionDefs = this._private._compoundDef?.sectionDefs
+    if (sectionDefs === undefined) {
+      return undefined
+    }
+
+    const resultSectionDefs: SectionDefDataModel[] = []
+    const sectionDefsByKind = new Map<string, SectionDefDataModel>()
+
+    for (const sectionDef of sectionDefs) {
+      if (
+        sectionDef.kind === 'user-defined' &&
+        sectionDef.header !== undefined
+      ) {
+        resultSectionDefs.push(sectionDef)
+        continue
+      }
+
+      if (sectionDef.memberDefs !== undefined) {
+        for (const memberDef of sectionDef.memberDefs) {
+          const adjustedSectionKind: string = this.adjustSectionKind(
+            sectionDef,
+            memberDef,
+            classUnqualifiedName
+          )
+
+          let mapSectionDef = sectionDefsByKind.get(adjustedSectionKind)
+          if (mapSectionDef === undefined) {
+            mapSectionDef = new SectionDefByKindDataModel(adjustedSectionKind)
+            sectionDefsByKind.set(adjustedSectionKind, mapSectionDef)
+          }
+          mapSectionDef.memberDefs ??= []
+          mapSectionDef.memberDefs.push(memberDef)
+        }
+      }
+
+      if (sectionDef.members !== undefined) {
+        for (const member of sectionDef.members) {
+          const adjustedSectionKind: string = this.adjustSectionKind(
+            sectionDef,
+            member,
+            classUnqualifiedName
+          )
+
+          let mapSectionDef = sectionDefsByKind.get(adjustedSectionKind)
+          if (mapSectionDef === undefined) {
+            mapSectionDef = new SectionDefByKindDataModel(adjustedSectionKind)
+            sectionDefsByKind.set(adjustedSectionKind, mapSectionDef)
+          }
+          mapSectionDef.members ??= []
+          mapSectionDef.members.push(member)
+        }
+      }
+    }
+
+    resultSectionDefs.push(...sectionDefsByKind.values())
+    return resultSectionDefs
+  }
+
+  // <xsd:simpleType name="DoxMemberKind">
+  //   <xsd:restriction base="xsd:string">
+  //     <xsd:enumeration value="define" />
+  //     <xsd:enumeration value="property" />
+  //     <xsd:enumeration value="event" />
+  //     <xsd:enumeration value="variable" />
+  //     <xsd:enumeration value="typedef" />
+  //     <xsd:enumeration value="enum" />
+  //     <xsd:enumeration value="function" />
+  //     <xsd:enumeration value="signal" />
+  //     <xsd:enumeration value="prototype" />
+  //     <xsd:enumeration value="friend" />
+  //     <xsd:enumeration value="dcop" />
+  //     <xsd:enumeration value="slot" />
+  //     <xsd:enumeration value="interface" />
+  //     <xsd:enumeration value="service" />
+  //   </xsd:restriction>
+  // </xsd:simpleType>
+
+  /**
+   * Adjusts section kind based on member type and context.
+   *
+   * @remarks
+   * Maps member kinds to appropriate section categories, handling
+   * special cases like operators, constructors, destructors, and
+   * various member types. Preserves visibility prefixes and applies
+   * context-specific adjustments.
+   *
+   * @param sectionDef - The section definition containing the member
+   * @param memberBase - The member whose section kind needs adjustment
+   * @param classUnqualifiedName - Optional class name for special method
+   *   detection
+   * @returns The adjusted section kind string
+   */
+  private adjustSectionKind(
+    sectionDef: SectionDefDataModel,
+    memberBase: AbstractMemberBaseType,
+    classUnqualifiedName: string | undefined
+  ): string {
+    // In general, adjust to member kind.
+    let adjustedSectionKind: string = memberBase.kind
+
+    switch (memberBase.kind) {
+      case 'function':
+        // If public/protected/private, preserve the prefix.
+        if (this.isOperator(memberBase.name)) {
+          adjustedSectionKind = sectionDef.computeAdjustedKind('operator')
+        } else if (classUnqualifiedName !== undefined) {
+          if (memberBase.name === classUnqualifiedName) {
+            adjustedSectionKind = sectionDef.computeAdjustedKind('constructorr')
+          } else if (
+            memberBase.name.replace('~', '') === classUnqualifiedName
+          ) {
+            adjustedSectionKind = sectionDef.computeAdjustedKind('destructor')
+          } else {
+            adjustedSectionKind = sectionDef.computeAdjustedKind(
+              'func',
+              'function'
+            )
+          }
+        } else {
+          adjustedSectionKind = sectionDef.computeAdjustedKind(
+            'func',
+            'function'
+          )
+        }
+        break
+
+      case 'variable':
+        adjustedSectionKind = sectionDef.computeAdjustedKind(
+          'attrib',
+          'variable'
+        )
+        break
+
+      case 'typedef':
+        adjustedSectionKind = sectionDef.computeAdjustedKind('type', 'typedef')
+        break
+
+      case 'slot':
+        adjustedSectionKind = sectionDef.computeAdjustedKind('slot')
+        break
+
+      // case 'define':
+      // case 'property':
+      // case 'event':
+      // case 'enum':
+      // case 'signal':
+      // case 'prototype':
+      // case 'friend':
+      // case 'dcop':
+      // case 'interface':
+      // case 'service':
+      default: {
+        // Adjust to member kind.
+        const { kind } = memberBase
+        adjustedSectionKind = kind
+        break
+      }
+    }
+
+    // console.log('adjustedSectionKind:', memberBase.kind, adjustedSectionKind)
+    return adjustedSectionKind
+  }
+
+  /**
+   * Performs late-stage initialisation after all compounds are loaded.
+   *
+   * @remarks
+   * Processes description content, location information, member sections,
+   * and inner compounds. Renders HTML strings and builds location sets
+   * for comprehensive compound documentation. Called after initial
+   * object creation phase.
+   */
+  initializeLate(): void {
+    const { workspace } = this.collection
+
+    const compoundDef = this._private._compoundDef
+    assert(compoundDef !== undefined)
+
+    if (compoundDef.briefDescription !== undefined) {
+      // console.log(compoundDef.briefDescription)
+
+      assert(compoundDef.briefDescription.children !== undefined)
+      if (compoundDef.briefDescription.children.length > 1) {
+        assert(
+          compoundDef.briefDescription.children[1] instanceof ParaDataModel
+        )
+        this.briefDescriptionHtmlString = workspace
+          .renderElementsArrayToString(
+            compoundDef.briefDescription.children[1].children,
+            'html'
+          )
+          .trim()
+      } else {
+        this.briefDescriptionHtmlString = workspace
+          .renderElementToString(compoundDef.briefDescription, 'html')
+          .trim()
+      }
+    }
+
+    if (compoundDef.detailedDescription !== undefined) {
+      // console.log(compoundDef.detailedDescription)
+      this.detailedDescriptionHtmlLines = workspace.renderElementToLines(
+        compoundDef.detailedDescription,
+        'html'
+      )
+    }
+
+    if (this.kind === 'page') {
+      // The location for pages is not usable.
+    } else if (this.kind === 'dir') {
+      // The location for folders is not used.
+    } else {
+      if (compoundDef.location !== undefined) {
+        this.locationLines = this.renderLocationToLines(compoundDef.location)
+      }
+    }
+
+    if (compoundDef.sectionDefs !== undefined) {
+      for (const sectionDef of compoundDef.sectionDefs) {
+        if (sectionDef.memberDefs !== undefined) {
+          for (const memberDef of sectionDef.memberDefs) {
+            if (memberDef.location !== undefined) {
+              const { file } = memberDef.location
+              this.locationSet.add(file)
+              if (memberDef.location.bodyfile !== undefined) {
+                this.locationSet.add(memberDef.location.bodyfile)
+              }
+            }
+          }
+        }
+      }
+    }
+
+    const { includes } = compoundDef
+    if (includes !== undefined) {
+      this.includes = includes
+    }
+
+    for (const innerKey of Object.keys(compoundDef)) {
+      if (
+        innerKey.startsWith('inner') &&
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access
+        (compoundDef as any)[innerKey] !== undefined
+      ) {
+        this.innerCompounds ??= new Map()
+        this.innerCompounds.set(innerKey, compoundDef)
+      }
+    }
+  }
+
+  /**
+   * Determines if a member name represents an operator function.
+   *
+   * @remarks
+   * Checks if the name starts with 'operator' followed by operator
+   * characters, identifying C++ operator overload functions for
+   * proper categorisation in documentation sections.
+   *
+   * @param name - The member name to check
+   * @returns True if the name represents an operator function
+   */
+  isOperator(name: string): boolean {
+    // Two word operators, like
+    if (
+      name.startsWith('operator') &&
+      ' =!<>+-*/%&|^~,"(['.includes(name.charAt(8))
+    ) {
+      return true
+    }
+    return false
+  }
+
+  // --------------------------------------------------------------------------
+
+  /**
+   * Renders the compound to an array of markdown lines.
+   *
+   * @remarks
+   * Abstract method that must be implemented by derived classes to
+   * generate the complete documentation content for the compound,
+   * including descriptions, member listings, and navigation elements.
+   *
+   * @param frontMatter - The frontmatter configuration for the page
+   * @returns Array of markdown strings representing the complete documentation
+   */
+  abstract renderToLines(frontMatter: FrontMatter): string[]
+
+  // --------------------------------------------------------------------------
+
+  renderBriefDescriptionToHtmlString({
+    briefDescriptionHtmlString,
+    todo = '',
+    morePermalink,
+  }: {
+    briefDescriptionHtmlString: string | undefined
+    todo?: string
+    morePermalink?: string | undefined
+  }): string {
+    let text = ''
+
+    if (!this.collection.workspace.options.suggestToDoDescriptions) {
+      todo = ''
+    }
+
+    if (briefDescriptionHtmlString === undefined && todo.length === 0) {
+      return ''
+    }
+
+    if (
+      briefDescriptionHtmlString !== undefined &&
+      briefDescriptionHtmlString.length > 0
+    ) {
+      text += '<p>'
+      text += briefDescriptionHtmlString
+      if (morePermalink !== undefined && morePermalink.length > 0) {
+        text += ` <a href="${morePermalink}">`
+        text += 'More...'
+        text += '</a>'
+      }
+      text += '</p>'
+    } else if (todo.length > 0) {
+      text += `TODO: add <code>@brief</code> to <code>${todo}</code>`
+    }
+
+    return text
+  }
+
+  renderDetailedDescriptionToHtmlLines({
+    briefDescriptionHtmlString,
+    detailedDescriptionHtmlLines,
+    todo = '',
+    showHeader,
+    showBrief = false,
+  }: {
+    briefDescriptionHtmlString?: string | undefined
+    detailedDescriptionHtmlLines: string[] | undefined
+    todo?: string
+    showHeader: boolean
+    showBrief?: boolean
+  }): string[] {
+    const lines: string[] = []
+
+    if (!this.collection.workspace.options.suggestToDoDescriptions) {
+      todo = ''
+    }
+
+    // const workspace = this.collection.workspace
+    if (showHeader) {
+      if (
+        (detailedDescriptionHtmlLines !== undefined &&
+          detailedDescriptionHtmlLines.length > 0) ||
+        todo.length > 0 ||
+        (showBrief &&
+          briefDescriptionHtmlString !== undefined &&
+          briefDescriptionHtmlString.length > 0)
+      ) {
+        lines.push('')
+        lines.push('## Description {#details}')
+      }
+    }
+
+    if (showBrief) {
+      if (showHeader) {
+        lines.push('')
+      }
+      if (
+        briefDescriptionHtmlString !== undefined &&
+        briefDescriptionHtmlString.length > 0
+      ) {
+        // lines.push(`<p>${briefDescriptionNoParaString}</p>`)
+        lines.push(`<p>${briefDescriptionHtmlString}</p>`)
+      } else if (todo.length > 0) {
+        lines.push(`TODO: add <code>@brief</code> to <code>${todo}</code>`)
+        console.log('TODO: add @brief to', todo)
+      }
+    }
+
+    // console.log(
+    //   util.inspect(detailedDescriptionLines, { compact: false, depth: 999 })
+    // )
+    if (
+      detailedDescriptionHtmlLines !== undefined &&
+      detailedDescriptionHtmlLines.length > 0
+    ) {
+      lines.push('')
+      lines.push(...detailedDescriptionHtmlLines)
+    } else if (todo.length > 0) {
+      lines.push('')
+      lines.push(`TODO: add <code>@details</code> to <code>${todo}</code>`)
+      console.log('TODO: add @details to', todo)
+    }
+
+    return lines
+  }
+
+  // --------------------------------------------------------------------------
+
+  hasInnerIndices(): boolean {
+    return this.innerCompounds !== undefined && this.innerCompounds.size > 0
+  }
+
+  renderInnerIndicesToLines({
+    suffixes = [],
+  }: {
+    suffixes?: string[]
+  }): string[] {
+    const lines: string[] = []
+
+    if (this.innerCompounds === undefined) {
+      return []
+    }
+
+    for (const innerKey of this.innerCompounds.keys()) {
+      if (innerKey.startsWith('inner')) {
+        const suffix = innerKey.substring(5)
+        if (!suffixes.includes(suffix)) {
+          console.warn(
+            innerKey,
+            'not processed for',
+            this.compoundName,
+            'in renderInnerIndicesToLines'
+          )
+          continue
+        }
+      }
+    }
+
+    const { workspace } = this.collection
+
+    for (const suffix of suffixes) {
+      const innerKey = `inner${suffix}`
+      const innerCompound: CompoundDefDataModel | undefined =
+        this.innerCompounds.get(innerKey)
+      if (innerCompound === undefined) {
+        continue
+      }
+
+      const innerObjects =
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-explicit-any
+        (innerCompound as any)[innerKey] as AbstractRefType[] | undefined
+
+      if (innerObjects === undefined || innerObjects.length === 0) {
+        continue
+      }
+
+      lines.push('')
+      lines.push(
+        `## ${
+          suffix === 'Dirs'
+            ? 'Folders'
+            : suffix === 'Groups'
+              ? 'Topics'
+              : suffix
+        } Index`
+      )
+
+      lines.push('')
+      lines.push('<table class="doxyMembersIndex">')
+
+      for (const innerObject of innerObjects) {
+        // console.log(
+        //   util.inspect(innerObject, { compact: false, depth: 999 })
+        // )
+        const innerDataObject = workspace.viewModel.compoundsById.get(
+          innerObject.refid
+        )
+        if (innerDataObject !== undefined) {
+          const { kind } = innerDataObject
+          const itemType =
+            kind === 'dir' ? 'folder' : kind === 'group' ? '&nbsp;' : kind
+
+          const permalink = workspace.getPagePermalink(innerObject.refid)
+
+          // Debatable. The compound name has the full namespace,
+          // the index has the template signature.
+          const name = this.collection.workspace.renderString(
+            innerDataObject.indexName,
+            'html'
+          )
+
+          let itemName = ''
+          if (permalink !== undefined && permalink.length > 0) {
+            itemName = `<a href="${permalink}">${name}</a>`
+          } else {
+            itemName = name
+          }
+
+          const childrenLines: string[] = []
+
+          const morePermalink =
+            innerDataObject.detailedDescriptionHtmlLines !== undefined &&
+            permalink !== undefined
+              ? `${permalink}/#details`
+              : undefined
+          if (
+            innerDataObject.briefDescriptionHtmlString !== undefined &&
+            innerDataObject.briefDescriptionHtmlString.length > 0
+          ) {
+            childrenLines.push(
+              this.renderBriefDescriptionToHtmlString({
+                briefDescriptionHtmlString:
+                  innerDataObject.briefDescriptionHtmlString,
+                morePermalink,
+              })
+            )
+          }
+
+          lines.push('')
+
+          lines.push(
+            ...this.collection.workspace.renderMembersIndexItemToHtmlLines({
+              type: itemType,
+              name: itemName,
+              childrenLines,
+            })
+          )
+        } else {
+          lines.push('')
+
+          const itemType = 'class'
+          const { text: itemName } = innerObject
+          lines.push(
+            ...this.collection.workspace.renderMembersIndexItemToHtmlLines({
+              type: itemType,
+              name: itemName,
+              childrenLines: [],
+            })
+          )
+
+          if (this.collection.workspace.options.debug) {
+            console.warn(innerObject)
+          }
+          if (this.collection.workspace.options.verbose) {
+            console.warn(
+              'Object definition not found, rendered summarily in ' +
+                'renderInnerIndicesToLines()'
+            )
+          }
+        }
+      }
+
+      lines.push('')
+      lines.push('</table>')
+    }
+
+    return lines
+  }
+
+  /**
+   * Renders an index table of concept compounds to markdown lines.
+   *
+   * @remarks
+   * Generates a `## Concepts Index` section containing an HTML table
+   * of concept entries. Each entry includes a hyperlinked name when a
+   * permalink is available, and an optional brief description with a
+   * `More...` link when detailed description content is present.
+   *
+   * @param concepts - Array of concept compounds to render in the index
+   * @returns Array of markdown strings representing the concepts index
+   */
+  renderConceptsIndexToLines(concepts: Concept[]): string[] {
+    const lines: string[] = []
+
+    lines.push('')
+    lines.push('## Concepts Index')
+
+    lines.push('')
+    lines.push('<table class="doxyMembersIndex">')
+
+    for (const concept of concepts) {
+      const itemType = 'concept'
+
+      const permalink = this.collection.workspace.getPagePermalink(concept.id)
+
+      let itemName = ''
+      if (permalink !== undefined && permalink.length > 0) {
+        itemName = `<a href="${permalink}">${concept.indexName}</a>`
+      } else {
+        itemName = concept.indexName
+      }
+
+      const childrenLines: string[] = []
+
+      const morePermalink =
+        concept.detailedDescriptionHtmlLines !== undefined &&
+        permalink !== undefined
+          ? `${permalink}/#details`
+          : undefined
+      if (
+        concept.briefDescriptionHtmlString !== undefined &&
+        concept.briefDescriptionHtmlString.length > 0
+      ) {
+        childrenLines.push(
+          this.renderBriefDescriptionToHtmlString({
+            briefDescriptionHtmlString: concept.briefDescriptionHtmlString,
+            morePermalink,
+          })
+        )
+      }
+
+      lines.push('')
+
+      lines.push(
+        ...this.collection.workspace.renderMembersIndexItemToHtmlLines({
+          type: itemType,
+          name: itemName,
+          childrenLines,
+        })
+      )
+    }
+
+    lines.push('')
+    lines.push('</table>')
+
+    return lines
+  }
+
+  hasSections(): boolean {
+    return this.sections.length > 0
+  }
+
+  renderSectionIndicesToLines(): string[] {
+    const lines: string[] = []
+
+    for (const section of this.sections) {
+      // console.log(sectionDef)
+      lines.push(...section.renderIndexToLines())
+    }
+
+    return lines
+  }
+
+  // --------------------------------------------------------------------------
+
+  renderIncludesIndexToLines(): string[] {
+    const lines: string[] = []
+
+    const { workspace } = this.collection
+
+    if (this.includes !== undefined) {
+      const includeLines = workspace.renderElementsArrayToLines(
+        this.includes,
+        'html'
+      )
+      lines.push('')
+      lines.push('## Included Headers')
+
+      lines.push('')
+      lines.push(`<div class="doxyIncludesList">${includeLines[0]}`)
+
+      for (const includeLine of includeLines.slice(1)) {
+        lines.push(includeLine)
+      }
+
+      lines.push('</div>')
+    }
+
+    return lines
+  }
+
+  // --------------------------------------------------------------------------
+
+  renderSectionsToLines(): string[] {
+    const lines: string[] = []
+
+    for (const section of this.sections) {
+      lines.push(...section.renderToLines())
+    }
+
+    return lines
+  }
+
+  renderLocationToLines(location: LocationDataModel | undefined): string[] {
+    const lines: string[] = []
+    let text = ''
+
+    const { workspace } = this.collection
+
+    if (location !== undefined) {
+      // console.log('location.file:', location.file)
+      if (location.file.includes('[')) {
+        // Ignore cases like `[generated]`, encountered in llvm.
+        return lines
+      }
+
+      // console.log(
+      //   'renderLocationToLines', this.kind, this.compoundName, this.id
+      // )
+      const file = workspace.filesByPath.get(location.file)
+      if (file !== undefined) {
+        const permalink: string | undefined = workspace.getPagePermalink(
+          file.id
+        )
+
+        if (
+          location.bodyfile !== undefined &&
+          location.file !== location.bodyfile
+        ) {
+          text += '<p>'
+          text += 'Declaration '
+          if (location.line !== undefined) {
+            text += 'at line '
+            const paddedLine = location.line.toString().padStart(5, '0')
+            const lineAttribute = `l${paddedLine}`
+            if (
+              permalink !== undefined &&
+              permalink.length > 0 &&
+              file.listingLineNumbers.has(location.line.valueOf())
+            ) {
+              text +=
+                `<a href="${permalink}/#${lineAttribute}">` +
+                workspace.renderString(location.line.toString(), 'html') +
+                `</a>`
+            } else {
+              text += location.line.toString()
+            }
+            text += ' of file '
+          } else {
+            text += ' in file '
+          }
+          const locationFile = workspace.renderString(
+            path.basename(location.file),
+            'html'
+          )
+          if (permalink !== undefined && permalink.length > 0) {
+            text += `<a href="${permalink}">${locationFile}</a>`
+          } else {
+            text += locationFile
+          }
+
+          const definitionFile = workspace.filesByPath.get(location.bodyfile)
+          if (definitionFile !== undefined) {
+            const definitionPermalink = workspace.getPagePermalink(
+              definitionFile.id
+            )
+
+            text += ', definition '
+            if (location.bodystart !== undefined) {
+              text += 'at line '
+              const lineStart = `l${location.bodystart
+                .toString()
+                .padStart(5, '0')}`
+
+              if (
+                definitionPermalink !== undefined &&
+                definitionPermalink.length > 0 &&
+                definitionFile.listingLineNumbers.has(
+                  location.bodystart.valueOf()
+                )
+              ) {
+                const bodyStart = workspace.renderString(
+                  location.bodystart.toString(),
+                  'html'
+                )
+                text +=
+                  `<a href="${definitionPermalink}/#${lineStart}">` +
+                  bodyStart +
+                  '</a>'
+              } else {
+                text += location.bodystart.toString()
+              }
+              text += ' of file '
+            } else {
+              text += ' in file '
+            }
+            const locationBodyFile = workspace.renderString(
+              path.basename(location.bodyfile),
+              'html'
+            )
+            if (
+              definitionPermalink !== undefined &&
+              definitionPermalink.length > 0
+            ) {
+              text +=
+                `<a href="${definitionPermalink}">` + `${locationBodyFile}</a>`
+            } else {
+              text += locationBodyFile
+            }
+          } else {
+            if (this.collection.workspace.options.verbose) {
+              console.warn('File', location.bodyfile, 'not a location.')
+            }
+          }
+          text += '.'
+          text += '</p>'
+          text += '\n'
+        } else {
+          text += '<p>'
+          text += 'Definition '
+          if (location.line !== undefined) {
+            text += 'at line '
+            const paddedLine = location.line.toString().padStart(5, '0')
+            const lineAttribute = `l${paddedLine}`
+            if (
+              permalink !== undefined &&
+              permalink.length > 0 &&
+              file.listingLineNumbers.has(location.line.valueOf())
+            ) {
+              const lineStr = location.line.toString()
+              const lineHtml = workspace.renderString(lineStr, 'html')
+              text +=
+                `<a href="${permalink}/#${lineAttribute}">` + `${lineHtml}</a>`
+            } else {
+              text += location.line.toString()
+            }
+            text += ' of file '
+          } else {
+            text += ' in file '
+          }
+          const locationFile = workspace.renderString(
+            path.basename(location.file),
+            'html'
+          )
+          if (permalink !== undefined && permalink.length > 0) {
+            text += `<a href="${permalink}">${locationFile}</a>`
+          } else {
+            text += locationFile
+          }
+          text += '.'
+          text += '</p>'
+          text += '\n'
+        }
+      } else {
+        if (this.collection.workspace.options.verbose) {
+          console.warn('File', location.file, 'not a known location.')
+        }
+      }
+    }
+
+    if (text.length > 0) {
+      lines.push('')
+      lines.push(text)
+    }
+
+    return lines
+  }
+
+  renderGeneratedFromToLines(): string[] {
+    const lines: string[] = []
+
+    if (this.locationSet.size > 0) {
+      lines.push('')
+      lines.push('<hr/>')
+      lines.push('')
+      lines.push(
+        `The documentation for this ${this.kind} was generated from the ` +
+          `following file${this.locationSet.size > 1 ? 's' : ''}:`
+      )
+      lines.push('')
+
+      lines.push('<ul>')
+
+      const { workspace } = this.collection
+
+      const sortedFiles = [...this.locationSet].sort((a, b) =>
+        a.localeCompare(b)
+      )
+      for (const fileName of sortedFiles) {
+        // console.log('search', fileName)
+        const fileNameEscaped = workspace.renderString(
+          path.basename(fileName),
+          'html'
+        )
+        const file = workspace.filesByPath.get(fileName)
+        if (file !== undefined) {
+          const permalink: string | undefined = workspace.getPagePermalink(
+            file.id
+          )
+          if (permalink !== undefined && permalink.length > 0) {
+            lines.push(`<li><a href="${permalink}">${fileNameEscaped}</a></li>`)
+          } else {
+            lines.push(`<li>${fileNameEscaped}</li>`)
+          }
+        } else {
+          lines.push(`<li>${fileNameEscaped}</li>`)
+        }
+      }
+      lines.push('</ul>')
+    }
+
+    return lines
+  }
+
+  renderReferencesToHtmlString(
+    references: ReferenceDataModel[] | undefined
+  ): string {
+    let text = ''
+
+    if (references === undefined || references.length === 0) {
+      return ''
+    }
+
+    const { workspace } = this.collection
+
+    const referenceLines: string[] = []
+
+    for (const reference of references) {
+      referenceLines.push(workspace.renderElementToString(reference, 'html'))
+    }
+
+    text += '<p>'
+    if (referenceLines.length === 1) {
+      text += 'Reference '
+    } else {
+      text += 'References '
+    }
+    text += joinWithLast(referenceLines, ', ', ' and ')
+    text += '.'
+    text += '</p>'
+    text += '\n'
+
+    return text
+  }
+
+  renderReferencedByToHtmlString(
+    referencedBy: ReferencedByDataModel[] | undefined
+  ): string {
+    let text = ''
+
+    if (referencedBy === undefined || referencedBy.length === 0) {
+      return ''
+    }
+
+    const { workspace } = this.collection
+
+    const referenceLines: string[] = []
+
+    for (const reference of referencedBy) {
+      referenceLines.push(workspace.renderElementToString(reference, 'html'))
+    }
+
+    text += '<p>'
+    text += 'Referenced by '
+    text += joinWithLast(referenceLines, ', ', ' and ')
+    text += '.'
+    text += '</p>'
+    text += '\n'
+
+    return text
+  }
+
+  // --------------------------------------------------------------------------
+
+  /**
+   * Return an array of types, like `class T`, or `class U = T`, or `N T::* MP`
+   * @param templateParamList
+   * @returns
+   */
+
+  collectTemplateParameters({
+    templateParamList,
+    withDefaults = false,
+  }: {
+    templateParamList: TemplateParamListDataModel | undefined
+    withDefaults?: boolean
+  }): string[] {
+    if (templateParamList?.params === undefined) {
+      return []
+    }
+
+    const templateParameters: string[] = []
+
+    for (const param of templateParamList.params) {
+      // console.log(util.inspect(param, { compact: false, depth: 999 }))
+      assert(param.type !== undefined)
+
+      let paramString = ''
+      assert(param.type.children !== undefined)
+      for (const child of param.type.children) {
+        if (typeof child === 'string') {
+          paramString += child
+        } else if ((child as object) instanceof RefTextDataModel) {
+          paramString += (child as RefTextDataModel).text
+        }
+      }
+
+      if (param.declname !== undefined) {
+        paramString += ` ${param.declname}`
+      }
+
+      if (withDefaults) {
+        if (param.defval !== undefined) {
+          const defval: DefValDataModel = param.defval
+          paramString += ' = '
+          assert(defval.children !== undefined)
+          for (const child of defval.children) {
+            if (typeof child === 'string') {
+              paramString += child
+            } else if (child instanceof RefTextDataModel) {
+              paramString += child.text
+            }
+          }
+        }
+      }
+
+      templateParameters.push(paramString)
+    }
+
+    return templateParameters
+  }
+
+  isTemplate(
+    templateParamList: TemplateParamListDataModel | undefined
+  ): boolean {
+    return (templateParamList?.params ?? []).length > 0
+  }
+
+  collectTemplateParameterNames(
+    templateParamList: TemplateParamListDataModel
+  ): string[] {
+    if (templateParamList.params === undefined) {
+      return []
+    }
+
+    const templateParameterNames: string[] = []
+
+    for (const param of templateParamList.params) {
+      // console.log(util.inspect(param, { compact: false, depth: 999 }))
+      assert(param.type !== undefined)
+
+      let paramString = ''
+
+      // declname? defname? order?
+      if (param.declname !== undefined) {
+        paramString += param.declname
+      } else {
+        assert(param.type.children !== undefined)
+        for (const child of param.type.children) {
+          if (typeof child === 'string') {
+            // Extract the parameter name, passed as `class T`.
+            paramString += child
+          } else if ((child as object) instanceof RefTextDataModel) {
+            paramString += (child as RefTextDataModel).text
+          }
+        }
+      }
+
+      const paramName = paramString
+        .replaceAll(/class /g, '')
+        .replaceAll(/typename /g, '')
+      templateParameterNames.push(paramName)
+    }
+    return templateParameterNames
+  }
+
+  renderTemplateParametersToString({
+    templateParamList,
+    withDefaults = false,
+  }: {
+    templateParamList: TemplateParamListDataModel | undefined
+    withDefaults?: boolean
+  }): string {
+    let text = ''
+
+    if (templateParamList?.params !== undefined) {
+      const templateParameters: string[] = this.collectTemplateParameters({
+        templateParamList,
+        withDefaults,
+      })
+      if (templateParameters.length > 0) {
+        text += `<${templateParameters.join(', ')}>`
+      }
+    }
+    return text
+  }
+
+  renderTemplateParameterNamesToString(
+    templateParamList: TemplateParamListDataModel | undefined
+  ): string {
+    let text = ''
+
+    if (templateParamList?.params !== undefined) {
+      const templateParameterNames: string[] =
+        this.collectTemplateParameterNames(templateParamList)
+      if (templateParameterNames.length > 0) {
+        text += `<${templateParameterNames.join(', ')}>`
+      }
+    }
+    return text
+  }
+
+  // --------------------------------------------------------------------------
+
+  /**
+   * Determines whether the compound has any displayable content.
+   *
+   * @remarks
+   * Checks for the presence of brief descriptions, detailed descriptions,
+   * or member sections to determine if the compound documentation page
+   * should be generated. Can be overridden by derived classes to add
+   * additional content checks.
+   *
+   * @returns True if the compound has content worth displaying
+   */
+  hasAnyContent(): boolean {
+    if (
+      this.briefDescriptionHtmlString !== undefined &&
+      this.briefDescriptionHtmlString.length > 0
+    ) {
+      // console.log('has content brief', this.compoundName)
+      return true
+    }
+    if (
+      this.detailedDescriptionHtmlLines !== undefined &&
+      this.detailedDescriptionHtmlLines.length > 0
+    ) {
+      // console.log('has content details', this.compoundName)
+      return true
+    }
+    if (this.sections.length > 0) {
+      // console.log('has content sections.length', this)
+      return true
+    }
+
+    return false
+  }
+}
+
+// ----------------------------------------------------------------------------