contribute package:jot to dart-lang/labs

.github/ISSUE_TEMPLATE/jot.md

@@ -0,0 +1,5 @@
+---
+name: "package:jot"
+about: "Create a bug or file a feature request against package:jot."
+labels: "package:jot"
+---

.github/labeler.yml

@@ -20,6 +20,10 @@
   - changed-files:
     - any-glob-to-any-file: 'pkgs/io_file/**'
 
+'package:jot':
+  - changed-files:
+    - any-glob-to-any-file: 'pkgs/jot/**'
+
 'package:native_synchronization':
   - changed-files:
     - any-glob-to-any-file: 'pkgs/native_synchronization/**'

.github/workflows/jot.yml

@@ -0,0 +1,53 @@
+name: package:jot
+
+permissions: read-all
+
+on:
+  # Run CI on pushes to the main branch, and on PRs against main.
+  push:
+    branches: [ main ]
+    paths:
+      - '.github/workflows/jot.yml'
+      - 'pkgs/jot/**'
+  pull_request:
+    branches: [ main ]
+    paths:
+      - '.github/workflows/jot.yml'
+      - 'pkgs/jot/**'
+  schedule:
+    - cron: '0 0 * * 0' # weekly
+
+defaults:
+  run:
+    working-directory: pkgs/jot
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        sdk: [stable, dev]
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+      - uses: dart-lang/setup-dart@e51d8e571e22473a2ddebf0ef8a2123f0ab2c02c
+        with:
+          sdk: ${{ matrix.sdk }}
+
+      - run: dart pub get
+
+      - run: dart analyze --fatal-infos
+
+      - run: dart format --output=none --set-exit-if-changed .
+        if: ${{ matrix.sdk == 'stable' }}
+
+      # Ensure that the front-end is up to date.
+      - run: dart tool/build_web.dart --verify
+
+      # Ensure that we can build the front-end.
+      - run: dart tool/build_web.dart
+
+      - run: dart test
+
+      # Ensure that we can build the Dart SDK docs.
+      - run: dart tool/create_dart_sdk.dart

CODEOWNERS

@@ -6,4 +6,6 @@
 /pkgs/appengine/               @dart-lang/dart-pub-team
 /pkgs/gcloud/                  @dart-lang/dart-pub-team
 /pkgs/io_file                  @brianquinlan
+# TODO:
+# /pkgs/jot/
 /pkgs/native_synchronization/  @mraleph

pkgs/jot/.gitattributes

@@ -0,0 +1 @@
+lib/resources/script.js -diff linguist-generated=true

pkgs/jot/.gitignore

@@ -0,0 +1,13 @@
+# https://dart.dev/guides/libraries/private-files
+
+.dart_tool/
+pubspec.lock
+
+doc/api/
+doc/sdk/
+
+lib/resources/script.js.deps
+lib/resources/script.js.map
+
+test/fixtures/demo/doc/api/_resources/
+test/fixtures/demo/doc/api/**/*.html

pkgs/jot/CHANGELOG.md

@@ -0,0 +1,3 @@
+## 0.1.0-dev
+
+- initial version

pkgs/jot/LICENSE

@@ -0,0 +1,27 @@
+Copyright 2025, the Dart project authors.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above
+      copyright notice, this list of conditions and the following
+      disclaimer in the documentation and/or other materials provided
+      with the distribution.
+    * Neither the name of Google LLC nor the names of its
+      contributors may be used to endorse or promote products derived
+      from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

pkgs/jot/README.md

@@ -0,0 +1,59 @@
+[![package:jot](https://github.com/dart-lang/labs/actions/workflows/native_synchronization.yml/badge.svg)](https://github.com/dart-lang/labs/actions/workflows/jot.yml)
+
+An experimental documentation generator for Dart.
+
+## What's this?
+
+An experimental documentation generator for Dart; the main design features are:
+
+- fast generation
+- output one page per library and per class (instead of a page per symbol)
+- output rendered in a SPA web app
+- few configuration options for the CLI tool
+- designed to be used as a library for sophisticated use cases (documenting the
+  Dart SDK, the Flutter SDK, ...)
+
+## Status: experimental
+
+**NOTE**: This package is currently experimental and published under the
+[labs.dart.dev](https://dart.dev/dart-team-packages) pub publisher in order to
+solicit feedback.
+
+For packages in the labs.dart.dev publisher we generally plan to either graduate
+the package into a supported publisher (dart.dev, tools.dart.dev) after a period
+of feedback and iteration, or discontinue the package. These packages have a
+much higher expected rate of API and breaking changes.
+
+Your feedback is valuable and will help us evolve this package. For general
+feedback, suggestions, and comments, please file an issue in the
+[bug tracker](https://github.com/dart-lang/labs/issues).
+
+## Command-line usage
+
+```
+Generate API documentation for Dart projects.
+
+usage: dart bin/jot.dart <options> [<directory>]
+
+-h, --help             Print this command help.
+-o, --output           Configure the output directory.
+                       (defaults to "doc/api")
+    --[no-]markdown    Include LLM-friendly markdown summaries of the API.
+                       (defaults to on)
+    --serve=<port>     Serve live docs from the documented package.
+                       This serves on localhost and is useful for previewing docs while working on them.
+```
+
+## Markdown API summaries
+
+Markdown summaries of the package's libraries are emitted into doc/api.
+These are designed for use by agents and LLMs. They are a token dense
+representation of the API; for example, for most symbols, the first markdown
+sentence of the symbol is used (instead of the full dartdoc text). In a future
+version, code examples in the documentation will be preserved as these are
+valuable to LLMs.
+
+## Infima and Docusaurus
+
+The CSS page layout for this API generator are sourced from the
+[Docusaurus](https://docusaurus.io/) project.

pkgs/jot/analysis_options.yaml

@@ -0,0 +1,10 @@
+include: package:dart_flutter_team_lints/analysis_options.yaml
+
+analyzer: 
+  errors: 
+    sort_pub_dependencies: ignore
+    unreachable_from_main: ignore
+
+linter:
+  rules:
+    - unawaited_futures

pkgs/jot/bin/jot.dart

@@ -0,0 +1,100 @@
+// Copyright (c) 2025, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+import 'dart:io';
+
+import 'package:args/args.dart';
+import 'package:jot/jot.dart';
+import 'package:path/path.dart' as p;
+
+void main(List<String> args) async {
+  var parser = createArgsParser();
+  ArgResults results;
+
+  try {
+    results = parser.parse(args);
+  } catch (e) {
+    printUsage(parser, e);
+    exit(64);
+  }
+
+  var help = results['help'] as bool;
+  if (help) {
+    printUsage(parser);
+    exit(0);
+  }
+
+  var rest = results.rest;
+  var inDir = rest.isEmpty ? Directory.current : Directory(rest.first);
+  if (!inDir.existsSync()) {
+    stderr.writeln("error: '${inDir.path}' does not exist.");
+    exit(1);
+  }
+
+  Directory outDir;
+  if (results.wasParsed('output')) {
+    outDir = Directory(results['output'] as String);
+  } else {
+    outDir = Directory(p.join(inDir.path, results['output'] as String));
+  }
+
+  int? servePort;
+  if (results.wasParsed('serve')) {
+    servePort = int.tryParse(results['serve'] as String);
+  }
+
+  final markdown = results['markdown'] as bool;
+
+  var jot = Jot(inDir: inDir, outDir: outDir, markdown: markdown);
+
+  if (servePort == null) {
+    await jot.generate();
+  } else {
+    await jot.serve(servePort);
+  }
+}
+
+ArgParser createArgsParser() {
+  return ArgParser()
+    ..addFlag(
+      'help',
+      abbr: 'h',
+      negatable: false,
+      help: 'Print this command help.',
+    )
+    ..addOption(
+      'output',
+      abbr: 'o',
+      defaultsTo: 'doc/api',
+      help: 'Configure the output directory.',
+    )
+    ..addFlag(
+      'markdown',
+      aliases: ['md', 'llm'],
+      negatable: true,
+      defaultsTo: true,
+      help: 'Include LLM-friendly markdown summaries of the API.',
+    )
+    ..addOption(
+      'serve',
+      valueHelp: 'port',
+      help:
+          'Serve live docs from the documented package.\nThis serves on '
+          'localhost and is useful for previewing docs while working on them.',
+    );
+}
+
+void printUsage(ArgParser parser, [Object? error]) {
+  if (error != null) {
+    print(error);
+  } else {
+    print('Generate API documentation for Dart projects.');
+  }
+
+  print('');
+
+  print('usage: dart bin/jot.dart <options> [<directory>]');
+  print('');
+  print(parser.usage);
+}