forked from firka/flutter
Reorganize and clarify API doc generator (#132353)
## Description This cleans up a lot of issues with the API doc generation. Here are the main changes: - Rename `dartdoc.dart` to `create_api_docs.dart` - Move the bulk of the operations out of `dev/bots/docs.sh` into `create_api_docs.dart`. - Delete `dashing_postprocess.dart` and `java_and_objc.dart` and incorporate those operations into `create_api_docs.dart`. - Refactor the doc generation into more understandable classes - Bump the snippets tool version to 0.4.0 (the latest one) - Centralize the information gathering about the Flutter repo into the new `FlutterInformation` class. - Clean up the directory handling, and convert to using the `file` package for all file and directory paths. - Add an `--output` option to docs.sh that specifies the location of the output ZIP file containing the docs. - Defaults to placing the output in `dev/docs/api_docs.zip` (i.e. where the previous code generates the file). - Moved all document generation into a temporary folder that is removed once the documents are generated, to avoid VSCode and other IDEs trying to index the thousands of HTML and JS files in the docs output. - Updated pubspec dependencies. ## Tests - Added tests for doc generation.
This commit is contained in:
Greg Spencer
195
dev/tools/test/create_api_docs_test.dart
Normal file
195
dev/tools/test/create_api_docs_test.dart
Normal file
@@ -0,0 +1,195 @@
|
||||
// Copyright 2014 The Flutter Authors. 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:file/file.dart';
|
||||
import 'package:file/memory.dart';
|
||||
import 'package:platform/platform.dart';
|
||||
import 'package:pub_semver/pub_semver.dart';
|
||||
import 'package:test/test.dart';
|
||||
|
||||
import '../../../packages/flutter_tools/test/src/fake_process_manager.dart';
|
||||
import '../create_api_docs.dart' as apidocs;
|
||||
|
||||
void main() {
|
||||
test('getBranchName does not call git if env LUCI_BRANCH provided', () {
|
||||
final Platform platform = FakePlatform(
|
||||
environment: <String, String>{
|
||||
'LUCI_BRANCH': branchName,
|
||||
},
|
||||
);
|
||||
|
||||
final ProcessManager processManager = FakeProcessManager.list(
|
||||
<FakeCommand>[
|
||||
const FakeCommand(
|
||||
command: <String>['flutter', '--version', '--machine'],
|
||||
stdout: testVersionInfo,
|
||||
),
|
||||
],
|
||||
);
|
||||
|
||||
expect(
|
||||
apidocs.FlutterInformation(platform: platform, processManager: processManager).getBranchName(),
|
||||
branchName,
|
||||
);
|
||||
expect(processManager, hasNoRemainingExpectations);
|
||||
});
|
||||
|
||||
test('getBranchName calls git if env LUCI_BRANCH not provided', () {
|
||||
final Platform platform = FakePlatform(
|
||||
environment: <String, String>{},
|
||||
);
|
||||
|
||||
final ProcessManager processManager = FakeProcessManager.list(
|
||||
<FakeCommand>[
|
||||
const FakeCommand(
|
||||
command: <String>['flutter', '--version', '--machine'],
|
||||
stdout: testVersionInfo,
|
||||
),
|
||||
const FakeCommand(
|
||||
command: <String>['git', 'status', '-b', '--porcelain'],
|
||||
stdout: '## $branchName',
|
||||
),
|
||||
],
|
||||
);
|
||||
|
||||
expect(
|
||||
apidocs.FlutterInformation(platform: platform, processManager: processManager).getBranchName(),
|
||||
branchName,
|
||||
);
|
||||
expect(processManager, hasNoRemainingExpectations);
|
||||
});
|
||||
|
||||
test('getBranchName calls git if env LUCI_BRANCH is empty', () {
|
||||
final Platform platform = FakePlatform(
|
||||
environment: <String, String>{
|
||||
'LUCI_BRANCH': '',
|
||||
},
|
||||
);
|
||||
|
||||
final ProcessManager processManager = FakeProcessManager.list(
|
||||
<FakeCommand>[
|
||||
const FakeCommand(
|
||||
command: <String>['flutter', '--version', '--machine'],
|
||||
stdout: testVersionInfo,
|
||||
),
|
||||
const FakeCommand(
|
||||
command: <String>['git', 'status', '-b', '--porcelain'],
|
||||
stdout: '## $branchName',
|
||||
),
|
||||
],
|
||||
);
|
||||
|
||||
expect(
|
||||
apidocs.FlutterInformation(platform: platform, processManager: processManager).getBranchName(),
|
||||
branchName,
|
||||
);
|
||||
expect(processManager, hasNoRemainingExpectations);
|
||||
});
|
||||
|
||||
test("runPubProcess doesn't use the pub binary", () {
|
||||
final Platform platform = FakePlatform(
|
||||
environment: <String, String>{
|
||||
'FLUTTER_ROOT': '/flutter',
|
||||
},
|
||||
);
|
||||
final ProcessManager processManager = FakeProcessManager.list(
|
||||
<FakeCommand>[
|
||||
const FakeCommand(
|
||||
command: <String>['/flutter/bin/dart', 'pub', '--one', '--two'],
|
||||
),
|
||||
],
|
||||
);
|
||||
apidocs.FlutterInformation.instance =
|
||||
apidocs.FlutterInformation(platform: platform, processManager: processManager);
|
||||
|
||||
apidocs.runPubProcess(
|
||||
arguments: <String>['--one', '--two'],
|
||||
processManager: processManager,
|
||||
);
|
||||
|
||||
expect(processManager, hasNoRemainingExpectations);
|
||||
});
|
||||
|
||||
group('FlutterInformation', () {
|
||||
late FakeProcessManager fakeProcessManager;
|
||||
late FakePlatform fakePlatform;
|
||||
late MemoryFileSystem memoryFileSystem;
|
||||
late apidocs.FlutterInformation flutterInformation;
|
||||
|
||||
void setUpWithEnvironment(Map<String, String> environment) {
|
||||
fakePlatform = FakePlatform(environment: environment);
|
||||
flutterInformation = apidocs.FlutterInformation(
|
||||
filesystem: memoryFileSystem,
|
||||
processManager: fakeProcessManager,
|
||||
platform: fakePlatform,
|
||||
);
|
||||
apidocs.FlutterInformation.instance = flutterInformation;
|
||||
}
|
||||
|
||||
setUp(() {
|
||||
fakeProcessManager = FakeProcessManager.empty();
|
||||
memoryFileSystem = MemoryFileSystem();
|
||||
setUpWithEnvironment(<String, String>{});
|
||||
});
|
||||
|
||||
test('calls out to flutter if FLUTTER_VERSION is not set', () async {
|
||||
fakeProcessManager.addCommand(
|
||||
const FakeCommand(command: <Pattern>['flutter', '--version', '--machine'], stdout: testVersionInfo));
|
||||
fakeProcessManager.addCommand(
|
||||
const FakeCommand(command: <Pattern>['git', 'status', '-b', '--porcelain'], stdout: testVersionInfo));
|
||||
final Map<String, dynamic> info = flutterInformation.getFlutterInformation();
|
||||
expect(fakeProcessManager, hasNoRemainingExpectations);
|
||||
expect(info['frameworkVersion'], equals(Version.parse('2.5.0')));
|
||||
});
|
||||
test("doesn't call out to flutter if FLUTTER_VERSION is set", () async {
|
||||
setUpWithEnvironment(<String, String>{
|
||||
'FLUTTER_VERSION': testVersionInfo,
|
||||
});
|
||||
fakeProcessManager.addCommand(
|
||||
const FakeCommand(command: <Pattern>['git', 'status', '-b', '--porcelain'], stdout: testVersionInfo));
|
||||
final Map<String, dynamic> info = flutterInformation.getFlutterInformation();
|
||||
expect(fakeProcessManager, hasNoRemainingExpectations);
|
||||
expect(info['frameworkVersion'], equals(Version.parse('2.5.0')));
|
||||
});
|
||||
test('getFlutterRoot calls out to flutter if FLUTTER_ROOT is not set', () async {
|
||||
fakeProcessManager.addCommand(
|
||||
const FakeCommand(command: <Pattern>['flutter', '--version', '--machine'], stdout: testVersionInfo));
|
||||
fakeProcessManager.addCommand(
|
||||
const FakeCommand(command: <Pattern>['git', 'status', '-b', '--porcelain'], stdout: testVersionInfo));
|
||||
final Directory root = flutterInformation.getFlutterRoot();
|
||||
expect(fakeProcessManager, hasNoRemainingExpectations);
|
||||
expect(root.path, equals('/home/user/flutter'));
|
||||
});
|
||||
test("getFlutterRoot doesn't call out to flutter if FLUTTER_ROOT is set", () async {
|
||||
setUpWithEnvironment(<String, String>{'FLUTTER_ROOT': '/home/user/flutter'});
|
||||
final Directory root = flutterInformation.getFlutterRoot();
|
||||
expect(fakeProcessManager, hasNoRemainingExpectations);
|
||||
expect(root.path, equals('/home/user/flutter'));
|
||||
});
|
||||
test('parses version properly', () async {
|
||||
fakePlatform.environment['FLUTTER_VERSION'] = testVersionInfo;
|
||||
fakeProcessManager.addCommand(
|
||||
const FakeCommand(command: <Pattern>['git', 'status', '-b', '--porcelain'], stdout: testVersionInfo));
|
||||
final Map<String, dynamic> info = flutterInformation.getFlutterInformation();
|
||||
expect(info['frameworkVersion'], isNotNull);
|
||||
expect(info['frameworkVersion'], equals(Version.parse('2.5.0')));
|
||||
expect(info['dartSdkVersion'], isNotNull);
|
||||
expect(info['dartSdkVersion'], equals(Version.parse('2.14.0-360.0.dev')));
|
||||
});
|
||||
});
|
||||
}
|
||||
|
||||
const String branchName = 'stable';
|
||||
const String testVersionInfo = '''
|
||||
{
|
||||
"frameworkVersion": "2.5.0",
|
||||
"channel": "$branchName",
|
||||
"repositoryUrl": "git@github.com:flutter/flutter.git",
|
||||
"frameworkRevision": "0000000000000000000000000000000000000000",
|
||||
"frameworkCommitDate": "2021-07-28 13:03:40 -0700",
|
||||
"engineRevision": "0000000000000000000000000000000000000001",
|
||||
"dartSdkVersion": "2.14.0 (build 2.14.0-360.0.dev)",
|
||||
"flutterRoot": "/home/user/flutter"
|
||||
}
|
||||
''';
|
||||
@@ -1,98 +0,0 @@
|
||||
// Copyright 2014 The Flutter Authors. 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:platform/platform.dart';
|
||||
import 'package:test/test.dart';
|
||||
|
||||
import '../../../packages/flutter_tools/test/src/fake_process_manager.dart';
|
||||
import '../dartdoc.dart' show getBranchName, runPubProcess;
|
||||
|
||||
void main() {
|
||||
const String branchName = 'stable';
|
||||
test('getBranchName does not call git if env LUCI_BRANCH provided', () {
|
||||
final Platform platform = FakePlatform(
|
||||
environment: <String, String>{
|
||||
'LUCI_BRANCH': branchName,
|
||||
},
|
||||
);
|
||||
|
||||
final ProcessManager processManager = FakeProcessManager.empty();
|
||||
|
||||
expect(
|
||||
getBranchName(
|
||||
platform: platform,
|
||||
processManager: processManager,
|
||||
),
|
||||
branchName,
|
||||
);
|
||||
});
|
||||
|
||||
test('getBranchName calls git if env LUCI_BRANCH not provided', () {
|
||||
final Platform platform = FakePlatform(
|
||||
environment: <String, String>{},
|
||||
);
|
||||
|
||||
final ProcessManager processManager = FakeProcessManager.list(
|
||||
<FakeCommand>[
|
||||
const FakeCommand(
|
||||
command: <String>['git', 'status', '-b', '--porcelain'],
|
||||
stdout: '## $branchName',
|
||||
),
|
||||
],
|
||||
);
|
||||
|
||||
expect(
|
||||
getBranchName(
|
||||
platform: platform,
|
||||
processManager: processManager,
|
||||
),
|
||||
branchName,
|
||||
);
|
||||
expect(processManager, hasNoRemainingExpectations);
|
||||
});
|
||||
|
||||
test('getBranchName calls git if env LUCI_BRANCH is empty', () {
|
||||
final Platform platform = FakePlatform(
|
||||
environment: <String, String>{
|
||||
'LUCI_BRANCH': '',
|
||||
},
|
||||
);
|
||||
|
||||
final ProcessManager processManager = FakeProcessManager.list(
|
||||
<FakeCommand>[
|
||||
const FakeCommand(
|
||||
command: <String>['git', 'status', '-b', '--porcelain'],
|
||||
stdout: '## $branchName',
|
||||
),
|
||||
],
|
||||
);
|
||||
|
||||
expect(
|
||||
getBranchName(
|
||||
platform: platform,
|
||||
processManager: processManager,
|
||||
),
|
||||
branchName,
|
||||
);
|
||||
expect(processManager, hasNoRemainingExpectations);
|
||||
});
|
||||
|
||||
test("runPubProcess doesn't use the pub binary", () {
|
||||
final ProcessManager processManager = FakeProcessManager.list(
|
||||
<FakeCommand>[
|
||||
const FakeCommand(
|
||||
command: <String>['dart', 'pub', '--one', '--two'],
|
||||
),
|
||||
],
|
||||
);
|
||||
|
||||
runPubProcess(
|
||||
dartBinaryPath: 'dart',
|
||||
arguments: <String>['--one', '--two'],
|
||||
processManager: processManager,
|
||||
);
|
||||
|
||||
expect(processManager, hasNoRemainingExpectations);
|
||||
});
|
||||
}
|
||||
Reference in New Issue
Block a user