generateDocs method

void generateDocs(
  1. BaseRuntime runtime, {
  2. required String outDir,
})

Given a runtime implementation and an outDir, collects the global variables and extracts their LuaDoc information while traversing lua objects and their properties. The html will contain js and css markup to prettify the document.

The file will be generated at "outDir/index.html".

Implementation

void generateDocs(BaseRuntime runtime, {required String outDir}) {
  _html = '<html>';
  _html += '<script>$js</script>';
  _html += '<style>$css</style>';

  /// Start the toolbar
  _html += '''
    <header style="
      flex: 0 0 50px;
      display: flex;
      flex-direction: row;
      align-items: center;
      top: 0;
      z-index: 10;
      padding-left: 30px;
      padding-right: 30px;
      justify-content: center;
      ">''';
  _html += '<div class="version-info" style="margin:10px">';
  _html += '<span class="version-title" style="margin:10px">$title</span>';

  /// Optional versioning.
  if (version != null) {
    _html +=
        '<span class="version-number" style="margin:10px">$version</span>';
  }

  /// Optional date time of generation.
  if (dateTimeFormat != null) {
    _html +=
        '''
        <span class="version-datetime"
        style="margin:10px">
        Generated ${DateFormat(dateTimeFormat).format(DateTime.now())}
        </span>
        ''';
  }

  _html += '</div>';
  _html += '''
    </header>
  ''';

  /// Start the main content output.

  _html += switch (showSidebarIndex) {
    true =>
      '''
      <main style="
        flex: 1;
        display: flex;
        flex-direction: row;
      ">
      ''',
    false => '<main>',
  };

  /// Sorts content alphabetically.
  final sortedIndex = runtime.global.vars.entries.toList()
    ..sort((a, b) => a.key.compareTo(b.key));

  /// Visit each object and construct categories for the index listing.
  for (var MapEntry(:key, :value) in sortedIndex) {
    /// Visit and inspect the lua object for doc configurations.
    /// The return string will decorated html.
    _body += luaObj2Html(key, value);

    final String k = value.doc?.category ?? 'Utils';
    if (!_indexHtml.containsKey(k)) {
      _indexHtml[k] = '';
    }

    /// Build the index separately from the body.
    _indexHtml[k] = '${_indexHtml[k]!}<a href="#$key">$key</a><br/>';
  }

  if (showSidebarIndex) {
    /// Write out the content inside a sidebar div.
    _html += '''
      <div class="sidebar"
        style="
        order:1;
        position: sticky;
        top: 90px;
        flex: 0 1 230px;
        min-height: 0%;
        max-height: 95%;
        height: 90vh;
        overflow-y: auto;
        ">
      ''';
    _html += renderIndex();
    _html += '</div>';
  } else {
    /// Add an html button to return the reader to the top page index.
    _html += '<div id="floater"><a href="#">▲</a></div>';
    _html += renderIndex();

    /// Separate the index from the docs.
    _html += '<hr>';
  }

  /// Append the body to the output html.
  if (showSidebarIndex) {
    _html += '<div style="order:2;flex:1;padding:20px;">$_body</div>';
  } else {
    _html += '<div style="padding: 20px">$_body</div>';
  }
  _html += '</main>';
  _html += '</html>';

  /// Finally, write out the document on disk.
  final out = '$outDir/index.html';
  File(out).writeAsStringSync(_html);
}