Skip to content

Commit 8fbd870

Browse files
godofredocgodofredoc
authored
Add a script to post-process docs. (#112228)
1 parent e167162 commit 8fbd870

File tree

3 files changed

+323
-1
lines changed

3 files changed

+323
-1
lines changed

‎dev/bots/post_process_docs.dart‎

Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
// Copyright 2014 The Flutter Authors. All rights reserved.
2+
// Use of this source code is governed by a BSD-style license that can be
3+
// found in the LICENSE file.
4+
5+
import 'dart:convert';
6+
import 'dart:io';
7+
import 'package:intl/intl.dart';
8+
import 'package:meta/meta.dart';
9+
10+
import 'package:path/path.dart' as path;
11+
import 'package:platform/platform.dart' as platform;
12+
13+
import 'package:process/process.dart';
14+
15+
const String kDocsRoot = 'dev/docs';
16+
const String kPublishRoot = '$kDocsRoot/doc';
17+
18+
class CommandException implements Exception {}
19+
20+
Future<void> main() async {
21+
await postProcess();
22+
}
23+
24+
/// Post-processes an APIs documentation zip file to modify the footer and version
25+
/// strings for commits promoted to either beta or stable channels.
26+
Future<void> postProcess() async {
27+
final String revision = await gitRevision(fullLength: true);
28+
print('Docs revision being processed: $revision');
29+
final Directory tmpFolder = Directory.systemTemp.createTempSync();
30+
final String zipDestination = path.join(tmpFolder.path, 'api_docs.zip');
31+
32+
if (!Platform.environment.containsKey('SDK_CHECKOUT_PATH')) {
33+
print('SDK_CHECKOUT_PATH env variable is required for this script');
34+
exit(1);
35+
}
36+
final String checkoutPath = Platform.environment['SDK_CHECKOUT_PATH']!;
37+
final String docsPath = path.join(checkoutPath, 'dev', 'docs');
38+
await runProcessWithValidations(
39+
<String>[
40+
'curl',
41+
'-L',
42+
'https://storage.googleapis.com/flutter_infra_release/flutter/$revision/api_docs.zip',
43+
'--output',
44+
zipDestination,
45+
'--fail',
46+
],
47+
docsPath,
48+
);
49+
50+
// Unzip to docs folder.
51+
await runProcessWithValidations(
52+
<String>[
53+
'unzip',
54+
'-o',
55+
zipDestination,
56+
],
57+
docsPath,
58+
);
59+
60+
// Generate versions file.
61+
await runProcessWithValidations(
62+
<String>['flutter', '--version'],
63+
docsPath,
64+
);
65+
final File versionFile = File('version');
66+
final String version = versionFile.readAsStringSync();
67+
// Recreate footer
68+
final String publishPath = path.join(docsPath, 'doc', 'api', 'footer.js');
69+
final File footerFile = File(publishPath)..createSync(recursive: true);
70+
createFooter(footerFile, version);
71+
}
72+
73+
/// Gets the git revision of the current checkout. [fullLength] if true will return
74+
/// the full commit hash, if false it will return the first 10 characters only.
75+
Future<String> gitRevision({
76+
bool fullLength = false,
77+
@visibleForTesting platform.Platform platform = const platform.LocalPlatform(),
78+
@visibleForTesting ProcessManager processManager = const LocalProcessManager(),
79+
}) async {
80+
const int kGitRevisionLength = 10;
81+
82+
final ProcessResult gitResult = processManager.runSync(<String>['git', 'rev-parse', 'HEAD']);
83+
if (gitResult.exitCode != 0) {
84+
throw 'git rev-parse exit with non-zero exit code: ${gitResult.exitCode}';
85+
}
86+
final String gitRevision = (gitResult.stdout as String).trim();
87+
if (fullLength) {
88+
return gitRevision;
89+
}
90+
return gitRevision.length > kGitRevisionLength ? gitRevision.substring(0, kGitRevisionLength) : gitRevision;
91+
}
92+
93+
/// Wrapper function to run a subprocess checking exit code and printing stderr and stdout.
94+
/// [executable] is a string with the script/binary to execute, [args] is the list of flags/arguments
95+
/// and [workingDirectory] is as string to the working directory where the subprocess will be run.
96+
Future<void> runProcessWithValidations(
97+
List<String> command,
98+
String workingDirectory, {
99+
@visibleForTesting ProcessManager processManager = const LocalProcessManager(),
100+
}) async {
101+
final ProcessResult result =
102+
processManager.runSync(command, stdoutEncoding: utf8, workingDirectory: workingDirectory);
103+
if (result.exitCode == 0) {
104+
print('Stdout: ${result.stdout}');
105+
} else {
106+
print('StdErr: ${result.stderr}');
107+
throw CommandException();
108+
}
109+
}
110+
111+
/// Get the name of the release branch.
112+
///
113+
/// On LUCI builds, the git HEAD is detached, so first check for the env
114+
/// variable "LUCI_BRANCH"; if it is not set, fall back to calling git.
115+
Future<String> getBranchName({
116+
@visibleForTesting platform.Platform platform = const platform.LocalPlatform(),
117+
@visibleForTesting ProcessManager processManager = const LocalProcessManager(),
118+
}) async {
119+
final RegExp gitBranchRegexp = RegExp(r'^## (.*)');
120+
final String? luciBranch = platform.environment['LUCI_BRANCH'];
121+
if (luciBranch != null && luciBranch.trim().isNotEmpty) {
122+
return luciBranch.trim();
123+
}
124+
final ProcessResult gitResult = processManager.runSync(<String>['git', 'status', '-b', '--porcelain']);
125+
if (gitResult.exitCode != 0) {
126+
throw 'git status exit with non-zero exit code: ${gitResult.exitCode}';
127+
}
128+
final RegExpMatch? gitBranchMatch = gitBranchRegexp.firstMatch((gitResult.stdout as String).trim().split('\n').first);
129+
return gitBranchMatch == null ? '' : gitBranchMatch.group(1)!.split('...').first;
130+
}
131+
132+
/// Updates the footer of the api documentation with the correct branch and versions.
133+
/// [footerPath] is the path to the location of the footer js file and [version] is a
134+
/// string with the version calculated by the flutter tool.
135+
Future<void> createFooter(File footerFile, String version,
136+
{@visibleForTesting String? timestampParam,
137+
@visibleForTesting String? branchParam,
138+
@visibleForTesting String? revisionParam}) async {
139+
final String timestamp = timestampParam ?? DateFormat('yyyy-MM-dd HH:mm').format(DateTime.now());
140+
final String gitBranch = branchParam ?? await getBranchName();
141+
final String revision = revisionParam ?? await gitRevision();
142+
final String gitBranchOut = gitBranch.isEmpty ? '' : '• $gitBranch';
143+
footerFile.writeAsStringSync('''
144+
(function() {
145+
var span = document.querySelector('footer>span');
146+
if (span) {
147+
span.innerText = 'Flutter $version • $timestamp • $revision $gitBranchOut';
148+
}
149+
var sourceLink = document.querySelector('a.source-link');
150+
if (sourceLink) {
151+
sourceLink.href = sourceLink.href.replace('/master/', '/$revision/');
152+
}
153+
})();
154+
''');
155+
}

‎dev/bots/pubspec.yaml‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ environment:
77
dependencies:
88
args: 2.3.1
99
crypto: 3.0.2
10+
intl: 0.17.0
1011
flutter_devicelab:
1112
path: ../devicelab
1213
http_parser: 4.0.1
@@ -23,6 +24,7 @@ dependencies:
2324
async: 2.9.0 # THIS LINE IS AUTOGENERATED - TO UPDATE USE "flutter update-packages --force-upgrade"
2425
boolean_selector: 2.1.0 # THIS LINE IS AUTOGENERATED - TO UPDATE USE "flutter update-packages --force-upgrade"
2526
checked_yaml: 2.0.1 # THIS LINE IS AUTOGENERATED - TO UPDATE USE "flutter update-packages --force-upgrade"
27+
clock: 1.1.1 # THIS LINE IS AUTOGENERATED - TO UPDATE USE "flutter update-packages --force-upgrade"
2628
collection: 1.16.0 # THIS LINE IS AUTOGENERATED - TO UPDATE USE "flutter update-packages --force-upgrade"
2729
convert: 3.0.2 # THIS LINE IS AUTOGENERATED - TO UPDATE USE "flutter update-packages --force-upgrade"
2830
coverage: 1.6.1 # THIS LINE IS AUTOGENERATED - TO UPDATE USE "flutter update-packages --force-upgrade"
@@ -69,4 +71,4 @@ dependencies:
6971
dev_dependencies:
7072
test_api: 0.4.14
7173

72-
# PUBSPEC CHECKSUM: 09b7
74+
# PUBSPEC CHECKSUM: 7a48

‎dev/bots/test/post_process_docs_test.dart‎

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
// Copyright 2014 The Flutter Authors. All rights reserved.
2+
// Use of this source code is governed by a BSD-style license that can be
3+
// found in the LICENSE file.
4+
5+
import 'dart:io';
6+
7+
import 'package:file/memory.dart';
8+
import 'package:platform/platform.dart';
9+
10+
import '../../../packages/flutter_tools/test/src/fake_process_manager.dart';
11+
import '../post_process_docs.dart';
12+
import 'common.dart';
13+
14+
void main() async {
15+
group('getBranch', () {
16+
const String branchName = 'stable';
17+
test('getBranchName does not call git if env LUCI_BRANCH provided', () async {
18+
final Platform platform = FakePlatform(
19+
environment: <String, String>{
20+
'LUCI_BRANCH': branchName,
21+
},
22+
);
23+
final ProcessManager processManager = FakeProcessManager.empty();
24+
final String calculatedBranchName = await getBranchName(
25+
platform: platform,
26+
processManager: processManager,
27+
);
28+
expect(calculatedBranchName, branchName);
29+
});
30+
31+
test('getBranchName calls git if env LUCI_BRANCH not provided', () async {
32+
final Platform platform = FakePlatform(
33+
environment: <String, String>{},
34+
);
35+
36+
final ProcessManager processManager = FakeProcessManager.list(
37+
<FakeCommand>[
38+
const FakeCommand(
39+
command: <String>['git', 'status', '-b', '--porcelain'],
40+
stdout: '## $branchName',
41+
),
42+
],
43+
);
44+
45+
final String calculatedBranchName = await getBranchName(platform: platform, processManager: processManager);
46+
expect(
47+
calculatedBranchName,
48+
branchName,
49+
);
50+
expect(processManager, hasNoRemainingExpectations);
51+
});
52+
test('getBranchName calls git if env LUCI_BRANCH is empty', () async {
53+
final Platform platform = FakePlatform(
54+
environment: <String, String>{
55+
'LUCI_BRANCH': '',
56+
},
57+
);
58+
59+
final ProcessManager processManager = FakeProcessManager.list(
60+
<FakeCommand>[
61+
const FakeCommand(
62+
command: <String>['git', 'status', '-b', '--porcelain'],
63+
stdout: '## $branchName',
64+
),
65+
],
66+
);
67+
final String calculatedBranchName = await getBranchName(
68+
platform: platform,
69+
processManager: processManager,
70+
);
71+
expect(
72+
calculatedBranchName,
73+
branchName,
74+
);
75+
expect(processManager, hasNoRemainingExpectations);
76+
});
77+
});
78+
79+
group('gitRevision', () {
80+
test('Return short format', () async {
81+
const String commitHash = 'e65f01793938e13cac2d321b9fcdc7939f9b2ea6';
82+
final ProcessManager processManager = FakeProcessManager.list(
83+
<FakeCommand>[
84+
const FakeCommand(
85+
command: <String>['git', 'rev-parse', 'HEAD'],
86+
stdout: commitHash,
87+
),
88+
],
89+
);
90+
final String revision = await gitRevision(processManager: processManager);
91+
expect(processManager, hasNoRemainingExpectations);
92+
expect(revision, commitHash.substring(0, 10));
93+
});
94+
95+
test('Return full length', () async {
96+
const String commitHash = 'e65f01793938e13cac2d321b9fcdc7939f9b2ea6';
97+
final ProcessManager processManager = FakeProcessManager.list(
98+
<FakeCommand>[
99+
const FakeCommand(
100+
command: <String>['git', 'rev-parse', 'HEAD'],
101+
stdout: commitHash,
102+
),
103+
],
104+
);
105+
final String revision = await gitRevision(fullLength: true, processManager: processManager);
106+
expect(processManager, hasNoRemainingExpectations);
107+
expect(revision, commitHash);
108+
});
109+
});
110+
111+
group('runProcessWithValidation', () {
112+
test('With no error', () async {
113+
const List<String> command = <String>['git', 'rev-parse', 'HEAD'];
114+
final ProcessManager processManager = FakeProcessManager.list(
115+
<FakeCommand>[
116+
const FakeCommand(
117+
command: command,
118+
),
119+
],
120+
);
121+
await runProcessWithValidations(command, '', processManager: processManager);
122+
expect(processManager, hasNoRemainingExpectations);
123+
});
124+
125+
test('With error', () async {
126+
const List<String> command = <String>['git', 'rev-parse', 'HEAD'];
127+
final ProcessManager processManager = FakeProcessManager.list(
128+
<FakeCommand>[
129+
const FakeCommand(
130+
command: command,
131+
exitCode: 1,
132+
),
133+
],
134+
);
135+
try {
136+
await runProcessWithValidations(command, '', processManager: processManager);
137+
throw Exception('Exception was not thrown');
138+
} on CommandException catch (e) {
139+
expect(e, isA<Exception>());
140+
}
141+
});
142+
});
143+
144+
group('generateFooter', () {
145+
test('generated correctly', () async {
146+
const String expectedContent = '''
147+
(function() {
148+
var span = document.querySelector('footer>span');
149+
if (span) {
150+
span.innerText = 'Flutter 3.0.0 • 2022-09-22 14:09 • abcdef • stable';
151+
}
152+
var sourceLink = document.querySelector('a.source-link');
153+
if (sourceLink) {
154+
sourceLink.href = sourceLink.href.replace('/master/', '/abcdef/');
155+
}
156+
})();
157+
''';
158+
final MemoryFileSystem fs = MemoryFileSystem();
159+
final File footerFile = fs.file('/a/b/c/footer.js')..createSync(recursive: true);
160+
await createFooter(footerFile, '3.0.0', timestampParam: '2022-09-22 14:09', branchParam: 'stable', revisionParam: 'abcdef');
161+
final String content = await footerFile.readAsString();
162+
expect(content, expectedContent);
163+
});
164+
});
165+
}

0 commit comments

Comments
 (0)