Try out workspaces for dartdoc tooling

.gitattributes

@@ -9,11 +9,11 @@ lib/src/html/resources.g.dart linguist-generated=false
 
 # Don't force devs to manually resolve conflicts in generated files.
 # At the end of a rebase or a merge, the dev may still need to regenerate
-# these files with `dart run tool/task.dart build`.
+# these files with `dart run task build`.
 lib/resources/docs.dart.js merge=theirs
 lib/resources/docs.dart.js.map merge=theirs
 lib/resources/styles.css merge=theirs
 lib/src/generator/templates.aot_renderers_for_html.dart merge=theirs
 lib/src/generator/templates.aot_renderers_for_md.dart merge=theirs
 lib/src/generator/templates.runtime_renderers.dart merge=theirs
-web/sig.txt merge=theirs
+tool/dartdoc_web/sig.txt merge=theirs

.github/workflows/test.yaml

@@ -81,6 +81,6 @@ jobs:
           DARTDOC_BOT: ${{ matrix.job }}
       - name: ${{ matrix.job }}
         if: runner.os == 'Windows' && matrix.job == 'main'
-        run: dart run tool\task.dart buildbot
+        run: dart run task buildbot
         env:
           DARTDOC_BOT: ${{ matrix.job }}

CHANGELOG.md

@@ -89,8 +89,6 @@
 * Combine the two implementations of "library canonicalization." This should be
   a no-op. (#3781)
 * Simplify `Library.allModelElements`, but should be a no-op. (#3793)
-* Support the `--stats` flag for the 'doc sdk' task
-  (`dart tools/task.dart doc sdk --stats`). (#3791)
 * Make `CommentReferenceParser.codeRef` private. (#3771)
 * Make `PackageGraph.allLibraries` private. (#3792)
 * Remove the unnecessary Privacy mixin. (#3794)

CONTRIBUTING.md

@@ -25,13 +25,13 @@ start by opening an issue. Thanks!
    to the [changelog][] under the current `-wip` version.
 2. Please include a test for your change. `dartdoc` has both
    `package:test`-style unit tests as well as integration tests.
-   To run the tests, use `dart run tool/task.dart test`.
-3. For major changes, run both `dart run tool/task.dart compare sdk-warnings`
-   and `dart run tool/task.dart compare flutter-warnings`, and
+   To run the tests, use `dart run task test`.
+3. For major changes, run both `dart run task compare sdk-warnings`
+   and `dart run task compare flutter-warnings`, and
    include the summary results in your pull request.
 4. Be sure to format your Dart code using `dart format`,
    otherwise our CI will complain.
-5. Use `dart run tool/task.dart buildbot` before creating a pull request
+5. Use `dart run task buildbot` before creating a pull request
    to quickly check for common problems.
    Follow any instructions it outputs, then run again.
 6. Post your change via a pull request for review and integration!
@@ -43,21 +43,21 @@ check for behavior changes or try out your change on arbitrary packages.
 
 ```bash
 # Serve the latest version of the given package locally on port 9000.
-dart run tool/task.dart serve package --name=intl
+dart run task serve package --name=intl
 
 # Build the SDK docs with the head version and compare its warning
 # output and (rough) performance to the main version.
-dart run tool/task.dart compare sdk-warnings
+dart run task compare sdk-warnings
 
 # Serve the flutter docs built with the head version on port 8001.
-dart run tool/task.dart serve flutter
+dart run task serve flutter
 
 # Serve the test package (testing/test_package) on port 8002
-dart run tool/task.dart serve testing-package
+dart run task serve testing-package
 ```
 
 There are more commands added all the time,
-check out `tool/task.dart` to find each command or
+check out `tool/task/bin/task.dart` to find each command or
 learn how they are implemented.
 
 ## License

lib/src/mustachio/annotations.dart

@@ -71,7 +71,6 @@ class Context<T> {
 /// The specification of a renderer, as derived from a @Renderer annotation.
 ///
 /// This is only meant to be used by dartdoc's builders.
-@internal
 class RendererSpec {
   /// The name of the render function.
   final String name;

pubspec.yaml

@@ -1,11 +1,17 @@
 name: dartdoc
 version: 8.3.1-wip
-description: A non-interactive HTML documentation generator for Dart source code.
+description: >-
+  A non-interactive HTML documentation generator for Dart source code.
 repository: /~https://github.com/dart-lang/dartdoc
 
 environment:
   sdk: ^3.5.0
 
+workspace:
+  - tool/mustachio
+  - tool/task
+  - tool/dartdoc_web
+
 dependencies:
   analyzer: ^6.10.0
   args: ^2.4.1
@@ -24,15 +30,14 @@ dependencies:
 
 dev_dependencies:
   async: ^2.11.0
-  dart_style: ^2.3.7
   lints: ^5.0.0
   matcher: ^0.12.15
-  sass: ^1.80.4
+  mustachio:
+    path: tool/mustachio
   test: ^1.24.2
   test_descriptor: ^2.0.1
   test_process: ^2.0.3
   test_reflective_loader: ^0.2.2
-  web: ^1.1.0
 
 executables:
   dartdoc: null

test/mustachio/builder_test_base.dart

@@ -8,14 +8,12 @@ import 'package:analyzer/file_system/physical_file_system.dart';
 import 'package:analyzer/src/dart/analysis/analysis_context_collection.dart'
     show AnalysisContextCollectionImpl;
 import 'package:collection/collection.dart';
+import 'package:mustachio/mustachio.dart' as mustachio;
 import 'package:path/path.dart' as path;
 import 'package:test_descriptor/test_descriptor.dart' as d;
 
-import '../../tool/mustachio/builder.dart';
 import '../src/test_descriptor_utils.dart';
 
-export '../../tool/mustachio/builder.dart';
-
 /// The build package Asset for a copy of the Renderer annotation for tests.
 ///
 /// In testing builders, the builder cannot access both in-line assets specified
@@ -76,7 +74,7 @@ $sourceLibraryContent
     ]),
   ]).create();
   await d.dir('foo_package', [...additionalAssets()]).create();
-  await build(path.join(d.sandbox, 'foo_package', 'lib/foo.dart'),
+  await mustachio.build(path.join(d.sandbox, 'foo_package', 'lib/foo.dart'),
       root: path.join(d.sandbox, 'foo_package'));
 }
 
@@ -86,7 +84,7 @@ Future<LibraryElement> resolveGeneratedLibrary(String libraryPath) async {
     // TODO(jcollins-g): should we pass excluded directories here instead of
     // handling it ourselves?
     resourceProvider: PhysicalResourceProvider.INSTANCE,
-    sdkPath: sdkPath,
+    sdkPath: mustachio.sdkPath,
   );
   var analysisContext = contextCollection.contextFor(d.sandbox);
   final libraryResult =

tool/ci.sh

@@ -14,17 +14,17 @@ if [ "$DARTDOC_BOT" = "sdk-docs" ]; then
   # silence stdout but echo stderr
   echo ""
   echo "Building and validating SDK docs..."
-  dart run tool/task.dart validate sdk-docs
+  dart run task validate sdk-docs
   echo "SDK docs process finished"
 elif [ "$DARTDOC_BOT" = "flutter" ]; then
   echo "Running flutter dartdoc bot"
-  dart run tool/task.dart doc flutter
+  dart run task doc flutter
 elif [ "$DARTDOC_BOT" = "packages" ]; then
   echo "Running packages dartdoc bot"
-  dart run tool/task.dart doc package --name=access --version=">=3.0.0"
+  dart run task doc package --name=access --version=">=3.0.0"
   # Negative test for flutter_plugin_tools, make sure right error message is displayed.
-  dart run tool/task.dart doc package --name=flutter_plugin_tools --version=">=0.0.14+1" 2>&1 | grep "warning: package:flutter_plugin_tools has no documentable libraries"
+  dart run task doc package --name=flutter_plugin_tools --version=">=0.0.14+1" 2>&1 | grep "warning: package:flutter_plugin_tools has no documentable libraries"
 else
   echo "Running main dartdoc bot"
-  dart run tool/task.dart buildbot
+  dart run task buildbot
 fi

web/search.dart → tool/dartdoc_web/lib/search.dart

@@ -5,6 +5,7 @@
 import 'dart:convert';
 import 'dart:js_interop';
 
+// ignore: implementation_imports
 import 'package:dartdoc/src/search.dart';
 import 'package:web/web.dart';
 

tool/dartdoc_web/pubspec.yaml

@@ -0,0 +1,13 @@
+name: dartdoc_web
+description: Client side web code for dartdoc.
+publish_to: none
+
+resolution: workspace
+
+environment:
+  sdk: ^3.5.0
+
+dependencies:
+  dartdoc:
+    path: ../..
+  web: ^1.1.0

tool/dartdoc_web/sig.txt

@@ -0,0 +1 @@
+EEADF842B2AE78DEC9DD494D82525D85

web/docs.dart → tool/dartdoc_web/web/docs.dart

@@ -2,10 +2,10 @@
 // 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 'highlight.dart' as highlight;
-import 'search.dart' as search;
-import 'sidebars.dart' as sidebars;
-import 'theme.dart' as theme;
+import 'package:dartdoc_web/highlight.dart' as highlight;
+import 'package:dartdoc_web/search.dart' as search;
+import 'package:dartdoc_web/sidebars.dart' as sidebars;
+import 'package:dartdoc_web/theme.dart' as theme;
 
 void main() {
   sidebars.init();

tool/mustachio/builder.dart → tool/mustachio/lib/mustachio.dart

@@ -1,18 +1,24 @@
+// Copyright (c) 2020, 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:analyzer/dart/analysis/results.dart';
 import 'package:analyzer/dart/element/element.dart';
 import 'package:analyzer/dart/element/type.dart';
 import 'package:analyzer/file_system/physical_file_system.dart';
+// ignore: implementation_imports
 import 'package:analyzer/src/dart/analysis/analysis_context_collection.dart'
     show AnalysisContextCollectionImpl;
+// ignore: implementation_imports
 import 'package:dartdoc/src/mustachio/annotations.dart';
 import 'package:path/path.dart' as path;
 
-import 'codegen_aot_compiler.dart';
-import 'codegen_runtime_renderer.dart';
+import 'src/codegen_aot_compiler.dart';
+import 'src/codegen_runtime_renderer.dart';
 
-void main() async {
+Future<void> generateForDartdoc() async {
   await build(path.join('lib', 'src', 'generator', 'templates.dart'));
   await build(
     path.join('test', 'mustachio', 'foo.dart'),
@@ -28,7 +34,7 @@ Future<void> build(
   root ??= Directory.current.path;
   var contextCollection = AnalysisContextCollectionImpl(
     includedPaths: [root],
-    // TODO(jcollins-g): should we pass excluded directories here instead of
+    // TODO(srawlins): should we pass excluded directories here instead of
     // handling it ourselves?
     resourceProvider: PhysicalResourceProvider.INSTANCE,
     sdkPath: sdkPath,

tool/mustachio/codegen_aot_compiler.dart → tool/mustachio/lib/src/codegen_aot_compiler.dart

@@ -10,9 +10,13 @@ import 'package:analyzer/dart/element/type_provider.dart';
 import 'package:analyzer/dart/element/type_system.dart';
 import 'package:collection/collection.dart';
 import 'package:dart_style/dart_style.dart';
+// ignore: implementation_imports
 import 'package:dartdoc/src/mustachio/annotations.dart';
+// ignore: implementation_imports
 import 'package:dartdoc/src/mustachio/parser.dart';
+// ignore: implementation_imports
 import 'package:dartdoc/src/mustachio/renderer_base.dart';
+// ignore: implementation_imports
 import 'package:dartdoc/src/type_utils.dart';
 import 'package:meta/meta.dart';
 import 'package:path/path.dart' as path;

tool/mustachio/codegen_runtime_renderer.dart → tool/mustachio/lib/src/codegen_runtime_renderer.dart

@@ -10,7 +10,9 @@ import 'package:analyzer/dart/element/type.dart';
 import 'package:analyzer/dart/element/type_provider.dart';
 import 'package:analyzer/dart/element/type_system.dart';
 import 'package:dart_style/dart_style.dart';
+// ignore: implementation_imports
 import 'package:dartdoc/src/mustachio/annotations.dart';
+// ignore: implementation_imports
 import 'package:dartdoc/src/type_utils.dart';
 import 'package:path/path.dart' as path;
 

tool/mustachio/pubspec.yaml

@@ -0,0 +1,19 @@
+name: mustachio
+description: >-
+  A code generation-based Mustache render system designed with
+  dartdoc's needs in mind.
+publish_to: none
+
+resolution: workspace
+
+environment:
+  sdk: ^3.5.0
+
+dependencies:
+  analyzer: ^6.10.0
+  collection: ^1.17.0
+  dart_style: ^2.3.7
+  dartdoc:
+    path: ../..
+  meta: ^1.10.0
+  path: ^1.8.3