renderDocs function

DocHtmlResult renderDocs(List<Library> libraries)

Renders a list of Library objects into sidebar and content HTML.

Each library's Library.getDocs and Library.description are used to produce the output. Libraries with no documented functions are skipped.

Implementation

DocHtmlResult renderDocs(List<Library> libraries) {
  final sidebarBuf = StringBuffer();
  final contentBuf = StringBuffer();
  final usedAnchors = <String>{};
  var sectionIndex = 0;

  for (final lib in libraries) {
    final docs = lib.getDocs();
    if (docs.isEmpty) continue;
    final cat = _libraryDocName(lib, docs);
    final sectionId = 'section-$sectionIndex-${_escapeAttribute(cat)}';
    final anchors = <String, String>{
      for (final name in docs.keys) name: _uniqueAnchor(cat, name, usedAnchors),
    };
    sectionIndex++;

    sidebarBuf.writeln('<div class="section-group">');
    sidebarBuf.writeln(
      '<button class="section-toggle" type="button" '
      'aria-controls="$sectionId-nav" aria-expanded="true">'
      '<span class="toggle-icon" aria-hidden="true">v</span>'
      '<span>${_escape(cat)}</span></button>',
    );
    sidebarBuf.writeln('<div class="section-items" id="$sectionId-nav">');
    for (final name in docs.keys) {
      final href = _escapeAttribute(anchors[name]!);
      sidebarBuf.writeln('<a class="func" href="#$href">${_escape(name)}</a>');
    }
    sidebarBuf.writeln('</div>');
    sidebarBuf.writeln('</div>');

    contentBuf.writeln('<section class="section-group">');
    contentBuf.writeln(
      '<button class="section-toggle" type="button" '
      'aria-controls="$sectionId-content" aria-expanded="true">'
      '<span class="toggle-icon" aria-hidden="true">v</span>'
      '<span>${_escape(cat)}</span></button>',
    );
    contentBuf.writeln('<div class="section-items" id="$sectionId-content">');
    if (lib.description.isNotEmpty) {
      contentBuf.writeln(
        '<p class="library-desc">${_escape(lib.description)}</p>',
      );
    }

    for (final entry in docs.entries) {
      final name = entry.key;
      final doc = entry.value;
      final sig = _signatureText(name, doc);
      final anchor = anchors[name]!;

      contentBuf.writeln('<article class="func-entry">');
      contentBuf.writeln('<a id="${_escapeAttribute(anchor)}"></a>');
      contentBuf.writeln('<div class="func-signature">${_escape(sig)}</div>');
      contentBuf.writeln(
        '<div class="func-summary">${_escape(doc.summary)}</div>',
      );
      if (doc.params.isNotEmpty) {
        contentBuf.write(_paramRowsHtml(doc.params));
      }
      if (doc.returns != null) {
        contentBuf.writeln(
          '<div class="returns"><strong>Returns:</strong> '
          '${_escape(doc.returns!)}</div>',
        );
      }
      if (doc.example != null) {
        contentBuf.writeln(
          '<pre class="language-lua"><code class="language-lua">'
          '${_escape(doc.example!)}</code></pre>',
        );
      }
      contentBuf.writeln('</article>');
    }
    contentBuf.writeln('</div>');
    contentBuf.writeln('</section>');
  }

  return DocHtmlResult(
    sidebar: sidebarBuf.toString(),
    content: contentBuf.toString(),
  );
}