firka/flutter
3
0
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Reorganize and clarify API doc generator (#132353)

Browse Source 
## 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
2023-08-15 15:12:16 -07:00
committed by GitHub
parent 301577a34f
commit 899a29f830
8 changed files with 1384 additions and 938 deletions
Download Patch File Download Diff File Expand all files Collapse all files

29
dev/docs/dashing_postprocess.dart
View File

@@ -1,29 +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 'dart:io';
/// This changes the DocSetPlatformFamily key to be "dartlang" instead of the
/// name of the package (usually "flutter").
///
/// This is so that the IntelliJ plugin for Dash will be able to go directly to
/// the docs for a symbol from a keystroke. Without this, flutter isn't part
/// of the list of package names it searches. After this, it finds the flutter
/// docs because they're declared here to be part of the "dartlang" family of
/// docs.
///
/// Dashing doesn't have a way to configure this, so we modify the Info.plist
/// directly to make the change.
void main(List<String> args) {
final File infoPlist = File('flutter.docset/Contents/Info.plist');
String contents = infoPlist.readAsStringSync();
// Since I didn't want to add the XML package as a dependency just for this,
// I just used a regular expression to make this simple change.
final RegExp findRe = RegExp(r'(\s*<key>DocSetPlatformFamily</key>\s*<string>)[^<]+(</string>)', multiLine: true);
contents = contents.replaceAllMapped(findRe, (Match match) {
return '${match.group(1)}dartlang${match.group(2)}';
});
infoPlist.writeAsStringSync(contents);
}