Skip to content

Commit 9fced22

Browse files
devoncarewdevoncarew
authored
contribute package:jot to dart-lang/labs (#287)
1 parent 96c5a16 commit 9fced22

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

62 files changed

+21769
-0
lines changed

‎.github/ISSUE_TEMPLATE/jot.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
name: "package:jot"
3+
about: "Create a bug or file a feature request against package:jot."
4+
labels: "package:jot"
5+
---

‎.github/labeler.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,10 @@
2020
- changed-files:
2121
- any-glob-to-any-file: 'pkgs/io_file/**'
2222

23+
'package:jot':
24+
- changed-files:
25+
- any-glob-to-any-file: 'pkgs/jot/**'
26+
2327
'package:native_synchronization':
2428
- changed-files:
2529
- any-glob-to-any-file: 'pkgs/native_synchronization/**'

‎.github/workflows/jot.yml‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
name: package:jot
2+
3+
permissions: read-all
4+
5+
on:
6+
# Run CI on pushes to the main branch, and on PRs against main.
7+
push:
8+
branches: [ main ]
9+
paths:
10+
- '.github/workflows/jot.yml'
11+
- 'pkgs/jot/**'
12+
pull_request:
13+
branches: [ main ]
14+
paths:
15+
- '.github/workflows/jot.yml'
16+
- 'pkgs/jot/**'
17+
schedule:
18+
- cron: '0 0 * * 0' # weekly
19+
20+
defaults:
21+
run:
22+
working-directory: pkgs/jot
23+
24+
jobs:
25+
build:
26+
runs-on: ubuntu-latest
27+
strategy:
28+
fail-fast: false
29+
matrix:
30+
sdk: [stable, dev]
31+
steps:
32+
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
33+
- uses: dart-lang/setup-dart@e51d8e571e22473a2ddebf0ef8a2123f0ab2c02c
34+
with:
35+
sdk: ${{ matrix.sdk }}
36+
37+
- run: dart pub get
38+
39+
- run: dart analyze --fatal-infos
40+
41+
- run: dart format --output=none --set-exit-if-changed .
42+
if: ${{ matrix.sdk == 'stable' }}
43+
44+
# Ensure that the front-end is up to date.
45+
- run: dart tool/build_web.dart --verify
46+
47+
# Ensure that we can build the front-end.
48+
- run: dart tool/build_web.dart
49+
50+
- run: dart test
51+
52+
# Ensure that we can build the Dart SDK docs.
53+
- run: dart tool/create_dart_sdk.dart

‎CODEOWNERS‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,4 +6,6 @@
66
/pkgs/appengine/ @dart-lang/dart-pub-team
77
/pkgs/gcloud/ @dart-lang/dart-pub-team
88
/pkgs/io_file @brianquinlan
9+
# TODO:
10+
# /pkgs/jot/
911
/pkgs/native_synchronization/ @mraleph

‎pkgs/jot/.gitattributes‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
lib/resources/script.js -diff linguist-generated=true

‎pkgs/jot/.gitignore‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# https://dart.dev/guides/libraries/private-files
2+
3+
.dart_tool/
4+
pubspec.lock
5+
6+
doc/api/
7+
doc/sdk/
8+
9+
lib/resources/script.js.deps
10+
lib/resources/script.js.map
11+
12+
test/fixtures/demo/doc/api/_resources/
13+
test/fixtures/demo/doc/api/**/*.html

‎pkgs/jot/CHANGELOG.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
## 0.1.0-dev
2+
3+
- initial version

‎pkgs/jot/LICENSE‎

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

‎pkgs/jot/README.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
[![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)
2+
3+
An experimental documentation generator for Dart.
4+
5+
## What's this?
6+
7+
An experimental documentation generator for Dart; the main design features are:
8+
9+
- fast generation
10+
- output one page per library and per class (instead of a page per symbol)
11+
- output rendered in a SPA web app
12+
- few configuration options for the CLI tool
13+
- designed to be used as a library for sophisticated use cases (documenting the
14+
Dart SDK, the Flutter SDK, ...)
15+
16+
## Status: experimental
17+
18+
**NOTE**: This package is currently experimental and published under the
19+
[labs.dart.dev](https://dart.dev/dart-team-packages) pub publisher in order to
20+
solicit feedback.
21+
22+
For packages in the labs.dart.dev publisher we generally plan to either graduate
23+
the package into a supported publisher (dart.dev, tools.dart.dev) after a period
24+
of feedback and iteration, or discontinue the package. These packages have a
25+
much higher expected rate of API and breaking changes.
26+
27+
Your feedback is valuable and will help us evolve this package. For general
28+
feedback, suggestions, and comments, please file an issue in the
29+
[bug tracker](https://github.com/dart-lang/labs/issues).
30+
31+
## Command-line usage
32+
33+
```
34+
Generate API documentation for Dart projects.
35+
36+
usage: dart bin/jot.dart <options> [<directory>]
37+
38+
-h, --help Print this command help.
39+
-o, --output Configure the output directory.
40+
(defaults to "doc/api")
41+
--[no-]markdown Include LLM-friendly markdown summaries of the API.
42+
(defaults to on)
43+
--serve=<port> Serve live docs from the documented package.
44+
This serves on localhost and is useful for previewing docs while working on them.
45+
```
46+
47+
## Markdown API summaries
48+
49+
Markdown summaries of the package's libraries are emitted into doc/api.
50+
These are designed for use by agents and LLMs. They are a token dense
51+
representation of the API; for example, for most symbols, the first markdown
52+
sentence of the symbol is used (instead of the full dartdoc text). In a future
53+
version, code examples in the documentation will be preserved as these are
54+
valuable to LLMs.
55+
56+
## Infima and Docusaurus
57+
58+
The CSS page layout for this API generator are sourced from the
59+
[Docusaurus](https://docusaurus.io/) project.

‎pkgs/jot/analysis_options.yaml‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
include: package:dart_flutter_team_lints/analysis_options.yaml
2+
3+
analyzer:
4+
errors:
5+
sort_pub_dependencies: ignore
6+
unreachable_from_main: ignore
7+
8+
linter:
9+
rules:
10+
- unawaited_futures

0 commit comments

Comments
 (0)