Skip to content

Reorganize and clarify API doc generator #132353

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
auto-submit merged 5 commits into from
Aug 15, 2023
Merged

Reorganize and clarify API doc generator #132353

auto-submit merged 5 commits into from
Aug 15, 2023

Conversation

@gspencergoog
Copy link
Contributor

@gspencergoog gspencergoog commented Aug 11, 2023 •
edited
Loading

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.

@gspencergoog gspencergoog mentioned this pull request Aug 11, 2023
Merged
@github-actions github-actions bot added a: tests "flutter test", flutter_test, or one of our tests a: text input Entering text in a text field or keyboard related problems platform-ios iOS applications specifically tool Affects the "flutter" command-line tool. See also t: labels. framework flutter/packages/flutter repository. See also f: labels. engine flutter/engine related. See also e: labels. a: animation Animation APIs f: material design flutter/packages/flutter/material repository. a: accessibility Accessibility, e.g. VoiceOver or TalkBack. (aka a11y) a: internationalization Supporting other languages or locales. (aka i18n) f: scrolling Viewports, list views, slivers, etc. f: cupertino flutter/packages/flutter/cupertino repository d: api docs Issues with https://api.flutter.dev/ d: examples Sample code and demos f: gestures flutter/packages/flutter/gestures repository. a: desktop Running on desktop f: integration_test The flutter/packages/integration_test plugin labels Aug 14, 2023
@gspencergoog gspencergoog force-pushed the move_dartdoc_output branch 3 times, most recently from ed921b1 to d6e0b85 Compare August 14, 2023 22:26
@gspencergoog gspencergoog marked this pull request as ready for review August 14, 2023 22:38
Hixie
Hixie reviewed Aug 14, 2023
View reviewed changes
dev/tools/pubspec.yaml Outdated
Copy link
Contributor

@Hixie Hixie Aug 14, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

to make this change did you use flutter update-packages?

Copy link
Contributor Author

@gspencergoog gspencergoog Aug 15, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh, good point. I'll re-run that.

Hixie
Hixie approved these changes Aug 14, 2023
View reviewed changes
Copy link
Contributor

@Hixie Hixie left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

godofredoc
godofredoc approved these changes Aug 15, 2023
View reviewed changes
Copy link
Contributor

@godofredoc godofredoc left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Anything to consider or pay attention to on release candidate branches and stable?

@gspencergoog
Copy link
Contributor Author

gspencergoog commented Aug 15, 2023

Anything to consider or pay attention to on release candidate branches and stable?

This should generate the same dev/docs/api_docs.zip file as before, but I haven't tested the actual site deployment part, where it unpacks that ZIP file and uploads the site. How would I do that?

@gspencergoog gspencergoog removed a: tests "flutter test", flutter_test, or one of our tests a: text input Entering text in a text field or keyboard related problems platform-ios iOS applications specifically tool Affects the "flutter" command-line tool. See also t: labels. engine flutter/engine related. See also e: labels. a: animation Animation APIs f: material design flutter/packages/flutter/material repository. a: accessibility Accessibility, e.g. VoiceOver or TalkBack. (aka a11y) a: internationalization Supporting other languages or locales. (aka i18n) f: scrolling Viewports, list views, slivers, etc. f: cupertino flutter/packages/flutter/cupertino repository f: gestures flutter/packages/flutter/gestures repository. f: integration_test The flutter/packages/integration_test plugin labels Aug 15, 2023
@auto-submit auto-submit bot merged commit 899a29f into flutter:master Aug 15, 2023
jonahwilliams pushed a commit that referenced this pull request Aug 16, 2023
Revert "Reorganize and clarify API doc generator (#132353)"
adc4030 
This reverts commit 899a29f.
@jonahwilliams jonahwilliams mentioned this pull request Aug 16, 2023
Merged
auto-submit bot pushed a commit that referenced this pull request Aug 16, 2023
Revert "Reorganize and clarify API doc generator" (#132613)
909400d 
Reverts #132353

Educated guess that this is causing the docs failures: https://logs.chromium.org/logs/flutter/buildbucket/cr-buildbucket/8772644466113801713/+/u/Docs/Deploy_docs/Firebase_deploy/stdout
zanderso added a commit that referenced this pull request Aug 16, 2023
@zanderso
Revert "Reorganize and clarify API doc generator (#132353)"
d495f80 
This reverts commit 899a29f.
@zanderso zanderso mentioned this pull request Aug 16, 2023
Closed
@engine-flutter-autoroll engine-flutter-autoroll mentioned this pull request Aug 16, 2023
Closed
engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Aug 16, 2023
@engine-flutter-autoroll
899a29f Reorganize and clarify API doc generator (flutter/flutter#132353
acff836 
)
@engine-flutter-autoroll engine-flutter-autoroll mentioned this pull request Aug 16, 2023
Merged
engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Aug 16, 2023
@engine-flutter-autoroll
899a29f Reorganize and clarify API doc generator (flutter/flutter#132353
8d3d9bc 
)
auto-submit bot pushed a commit to flutter/packages that referenced this pull request Aug 16, 2023
@engine-flutter-autoroll
Roll Flutter from f0e7c51 to 2502b51 (15 revisions) (#4722)
63ba60c 
flutter/flutter@f0e7c51...2502b51

2023-08-16 [email protected] Roll Flutter Engine from f186f1e9dc88 to 70b5700b79f6 (1 revision) (flutter/flutter#132655)
2023-08-16 [email protected] Roll Flutter Engine from e8670f03a9b1 to f186f1e9dc88 (2 revisions) (flutter/flutter#132649)
2023-08-16 [email protected] Fix flutter_tools use of --local-engine-host (flutter/flutter#132648)
2023-08-16 [email protected] Roll Flutter Engine from 7cc6a5832a0e to e8670f03a9b1 (3 revisions) (flutter/flutter#132623)
2023-08-16 [email protected] Roll Flutter Engine from decaccfc421d to 7cc6a5832a0e (1 revision) (flutter/flutter#132621)
2023-08-16 [email protected] Roll Flutter Engine from 659cdfc5a568 to decaccfc421d (6 revisions) (flutter/flutter#132618)
2023-08-16 [email protected] Roll Flutter Engine from 7409ce4ba0a8 to 659cdfc5a568 (1 revision) (flutter/flutter#132612)
2023-08-16 [email protected] Revert "Reorganize and clarify API doc generator" (flutter/flutter#132613)
2023-08-16 [email protected] Roll Flutter Engine from a9da7212eacf to 7409ce4ba0a8 (5 revisions) (flutter/flutter#132609)
2023-08-16 [email protected] Roll Flutter Engine from 22f03ffdc290 to a9da7212eacf (4 revisions) (flutter/flutter#132608)
2023-08-16 [email protected] [Reland] #131609 (flutter/flutter#132555)
2023-08-15 [email protected] Explain the keyboard manager protocol (flutter/flutter#132533)
2023-08-15 [email protected] Fix extent for null returning builder in GridView (flutter/flutter#132511)
2023-08-15 [email protected] Reorganize and clarify API doc generator (flutter/flutter#132353)
2023-08-15 [email protected] Fixing a memory leak in About box/dialog overlays (flutter/flutter#130842)

If this roll has caused a breakage, revert this CL and stop the roller
using the controls here:
https://autoroll.skia.org/r/flutter-packages
Please CC [email protected],[email protected],[email protected] on the revert to ensure that a human
is aware of the problem.

To file a bug in Packages: https://github.com/flutter/flutter/issues/new/choose

To report a problem with the AutoRoller itself, please file a bug:
https://bugs.chromium.org/p/skia/issues/entry?template=Autoroller+Bug

Documentation for the AutoRoller is here:
https://skia.googlesource.com/buildbot/+doc/main/autoroll/README.md
@gspencergoog gspencergoog mentioned this pull request Aug 16, 2023
Merged
auto-submit bot pushed a commit that referenced this pull request Aug 17, 2023
@gspencergoog
Reland: "Reorganize and clarify API doc generator" (#132353) (#132710)
ced3e76 
## Description

This re-lands #132353 with some additional options for keeping around the staging directory, so that the recipe for publishing docs can give those options and have the staging directory left around for deploying to the website.

Reverted in #132613

## Related Issues
 - https://flutter-review.googlesource.com/c/recipes/+/49580
engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Nov 15, 2023
@engine-flutter-autoroll
899a29f Reorganize and clarify API doc generator (flutter/flutter#132353
8349d51 
)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@Hixie Hixie Hixie approved these changes

+2 more reviewers

@christopherfujino christopherfujino christopherfujino approved these changes

@godofredoc godofredoc godofredoc approved these changes

Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

a: desktop Running on desktop autosubmit Merge PR when tree becomes green via auto submit App d: api docs Issues with https://api.flutter.dev/ d: examples Sample code and demos framework flutter/packages/flutter repository. See also f: labels.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@gspencergoog @christopherfujino @Hixie @godofredoc