mirror of
https://github.com/dart-lang/sdk
synced 2024-10-14 14:53:37 +00:00
Initial 'dart doc' developer command
Initial 'dart doc' command for the unified 'dart' developer tool, over time replacing the exiting 'bin/dartdoc' tool. This is a second attempt after the previous got reverted: https://dart-review.googlesource.com/c/sdk/+/217980 The first attempt, which was already reviewed, is in patchset 1. Change-Id: Id9e0e572944ba032c32f3cebec579ab23d0df036 Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/220744 Commit-Queue: Michael Thomsen <mit@google.com> Reviewed-by: Ben Konyi <bkonyi@google.com> Reviewed-by: Samuel Rawlins <srawlins@google.com>
This commit is contained in:
parent
e774227a81
commit
7da2117892
|
@ -21,6 +21,7 @@ import 'src/commands/analyze.dart';
|
||||||
import 'src/commands/compile.dart';
|
import 'src/commands/compile.dart';
|
||||||
import 'src/commands/create.dart';
|
import 'src/commands/create.dart';
|
||||||
import 'src/commands/debug_adapter.dart';
|
import 'src/commands/debug_adapter.dart';
|
||||||
|
import 'src/commands/doc.dart';
|
||||||
import 'src/commands/fix.dart';
|
import 'src/commands/fix.dart';
|
||||||
import 'src/commands/language_server.dart';
|
import 'src/commands/language_server.dart';
|
||||||
import 'src/commands/migrate.dart';
|
import 'src/commands/migrate.dart';
|
||||||
|
@ -114,6 +115,7 @@ class DartdevRunner extends CommandRunner<int> {
|
||||||
addCommand(CreateCommand(verbose: verbose));
|
addCommand(CreateCommand(verbose: verbose));
|
||||||
addCommand(DebugAdapterCommand(verbose: verbose));
|
addCommand(DebugAdapterCommand(verbose: verbose));
|
||||||
addCommand(CompileCommand(verbose: verbose));
|
addCommand(CompileCommand(verbose: verbose));
|
||||||
|
addCommand(DocCommand(verbose: verbose));
|
||||||
addCommand(DevToolsCommand(
|
addCommand(DevToolsCommand(
|
||||||
verbose: verbose,
|
verbose: verbose,
|
||||||
customDevToolsPath: sdk.devToolsBinaries,
|
customDevToolsPath: sdk.devToolsBinaries,
|
||||||
|
|
89
pkg/dartdev/lib/src/commands/doc.dart
Normal file
89
pkg/dartdev/lib/src/commands/doc.dart
Normal file
|
@ -0,0 +1,89 @@
|
||||||
|
// Copyright (c) 2021, 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:async';
|
||||||
|
import 'dart:io' as io;
|
||||||
|
|
||||||
|
import 'package:dartdoc/dartdoc.dart';
|
||||||
|
import 'package:dartdoc/options.dart';
|
||||||
|
import 'package:path/path.dart' as path;
|
||||||
|
|
||||||
|
import '../core.dart';
|
||||||
|
import '../sdk.dart';
|
||||||
|
|
||||||
|
/// A command to create a new project from a set of templates.
|
||||||
|
class DocCommand extends DartdevCommand {
|
||||||
|
static const String cmdName = 'doc';
|
||||||
|
|
||||||
|
DocCommand({bool verbose = false})
|
||||||
|
: super(
|
||||||
|
cmdName,
|
||||||
|
'Generate HTML API documentation from Dart documentation comments.',
|
||||||
|
verbose,
|
||||||
|
) {
|
||||||
|
argParser.addOption(
|
||||||
|
'output-dir',
|
||||||
|
abbr: 'o',
|
||||||
|
defaultsTo: path.join('.', 'doc', 'api'),
|
||||||
|
help: 'Output directory',
|
||||||
|
);
|
||||||
|
argParser.addFlag(
|
||||||
|
'validate-links',
|
||||||
|
negatable: true,
|
||||||
|
help: 'Display context aware warnings for broken links (slow)',
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
@override
|
||||||
|
String get invocation => '${super.invocation} <input directory>';
|
||||||
|
|
||||||
|
@override
|
||||||
|
FutureOr<int> run() async {
|
||||||
|
// At least one argument, the input directory, is required.
|
||||||
|
if (argResults.rest.isEmpty) {
|
||||||
|
usageException("Error: Input directory not specified");
|
||||||
|
}
|
||||||
|
|
||||||
|
// Determine input directory.
|
||||||
|
final dir = io.Directory(argResults.rest[0]);
|
||||||
|
if (!dir.existsSync()) {
|
||||||
|
usageException("Error: Input directory doesn't exist: ${dir.path}");
|
||||||
|
}
|
||||||
|
|
||||||
|
// Parse options.
|
||||||
|
final options = [
|
||||||
|
'--input=${dir.path}',
|
||||||
|
'--output=${argResults['output-dir']}',
|
||||||
|
];
|
||||||
|
if (argResults['validate-links']) {
|
||||||
|
options.add('--validate-links');
|
||||||
|
} else {
|
||||||
|
options.add('--no-validate-links');
|
||||||
|
}
|
||||||
|
|
||||||
|
// Specify where dartdoc resources are located.
|
||||||
|
final resourcesPath =
|
||||||
|
path.absolute(sdk.sdkPath, 'bin', 'resources', 'dartdoc', 'resources');
|
||||||
|
options.add('--resources-dir=$resourcesPath');
|
||||||
|
|
||||||
|
final config = await parseOptions(pubPackageMetaProvider, options);
|
||||||
|
if (config == null) {
|
||||||
|
// There was an error while parsing options.
|
||||||
|
return 2;
|
||||||
|
}
|
||||||
|
|
||||||
|
// Call dartdoc.
|
||||||
|
if (verbose) {
|
||||||
|
log.stdout('Calling dartdoc with the following options: $options');
|
||||||
|
}
|
||||||
|
final packageConfigProvider = PhysicalPackageConfigProvider();
|
||||||
|
final packageBuilder = PubPackageBuilder(
|
||||||
|
config, pubPackageMetaProvider, packageConfigProvider);
|
||||||
|
final dartdoc = config.generateDocs
|
||||||
|
? await Dartdoc.fromContext(config, packageBuilder)
|
||||||
|
: await Dartdoc.withEmptyGenerator(config, packageBuilder);
|
||||||
|
dartdoc.executeGuarded();
|
||||||
|
return 0;
|
||||||
|
}
|
||||||
|
}
|
|
@ -17,6 +17,7 @@ dependencies:
|
||||||
dart2native:
|
dart2native:
|
||||||
path: ../dart2native
|
path: ../dart2native
|
||||||
dart_style: any
|
dart_style: any
|
||||||
|
dartdoc: any
|
||||||
dds:
|
dds:
|
||||||
path: ../dds
|
path: ../dds
|
||||||
devtools_server: any
|
devtools_server: any
|
||||||
|
|
70
pkg/dartdev/test/commands/doc_test.dart
Normal file
70
pkg/dartdev/test/commands/doc_test.dart
Normal file
|
@ -0,0 +1,70 @@
|
||||||
|
// Copyright (c) 2021, 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 'package:test/test.dart';
|
||||||
|
|
||||||
|
import '../utils.dart';
|
||||||
|
|
||||||
|
const int compileErrorExitCode = 64;
|
||||||
|
|
||||||
|
void main() {
|
||||||
|
group('doc', defineCompileTests, timeout: longTimeout);
|
||||||
|
}
|
||||||
|
|
||||||
|
void defineCompileTests() {
|
||||||
|
test('Passing no args fails', () async {
|
||||||
|
final p = project();
|
||||||
|
var result = await p.run(['doc']);
|
||||||
|
expect(result.stderr, contains('Input directory not specified'));
|
||||||
|
expect(result.exitCode, compileErrorExitCode);
|
||||||
|
});
|
||||||
|
|
||||||
|
test('--help', () async {
|
||||||
|
final p = project();
|
||||||
|
final result = await p.run(['doc', '--help']);
|
||||||
|
expect(
|
||||||
|
result.stdout,
|
||||||
|
contains('Usage: dart doc [arguments] <input directory>'),
|
||||||
|
);
|
||||||
|
|
||||||
|
expect(result.exitCode, 0);
|
||||||
|
});
|
||||||
|
|
||||||
|
test('Document a library', () async {
|
||||||
|
final source = '''
|
||||||
|
/// This is Foo. It uses [Bar].
|
||||||
|
class Foo {
|
||||||
|
Bar bar;
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Bar is very nice.
|
||||||
|
class Bar {
|
||||||
|
_i = 42;
|
||||||
|
}
|
||||||
|
''';
|
||||||
|
|
||||||
|
final p = project(mainSrc: 'void main() { print("Hello, World"); }');
|
||||||
|
p.file('lib/foo.dart', source);
|
||||||
|
final result = await p.run(['doc', '--validate-links', p.dirPath]);
|
||||||
|
print(
|
||||||
|
'exit: ${result.exitCode}, stderr:\n${result.stderr}\nstdout:\n${result.stdout}');
|
||||||
|
expect(result.stdout, contains('Documenting dartdev_temp'));
|
||||||
|
});
|
||||||
|
|
||||||
|
test('Document a library with broken link is flagged', () async {
|
||||||
|
final source = '''
|
||||||
|
/// This is Foo. It uses [Baz].
|
||||||
|
class Foo {
|
||||||
|
// Bar bar;
|
||||||
|
}
|
||||||
|
''';
|
||||||
|
|
||||||
|
final p = project(mainSrc: 'void main() { print("Hello, World"); }');
|
||||||
|
p.file('lib/foo.dart', source);
|
||||||
|
final result = await p.run(['doc', '--validate-links', p.dirPath]);
|
||||||
|
print(
|
||||||
|
'exit: ${result.exitCode}, stderr:\n${result.stderr}\nstdout:\n${result.stdout}');
|
||||||
|
expect(result.stdout, contains('Documenting dartdev_temp'));
|
||||||
|
});
|
||||||
|
}
|
|
@ -23,4 +23,4 @@ SNAPSHOT="$BIN_DIR/snapshots/dartdoc.dart.snapshot"
|
||||||
|
|
||||||
# We are running the snapshot in the built SDK.
|
# We are running the snapshot in the built SDK.
|
||||||
DART="$BIN_DIR/dart"
|
DART="$BIN_DIR/dart"
|
||||||
exec "$DART" "--packages=$BIN_DIR/resources/dartdoc/.packages" "$SNAPSHOT" "$@"
|
exec "$DART" "--packages=$BIN_DIR/resources/dartdoc/.packages" "$SNAPSHOT" "--resources-dir=$BIN_DIR/resources/dartdoc/resources/" "$@"
|
||||||
|
|
Loading…
Reference in a new issue