• Stars
    star
    113
  • Rank 303,402 (Top 7 %)
  • Language
    Dart
  • License
    BSD 3-Clause "New...
  • Created about 7 years ago
  • Updated 8 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Static assets for embedding into docs.flutter.io

assets-for-api-docs

This repo is used to host and serve static assets in support of docs.flutter.dev, as well as some manual tests that use specially-crafted graphics.

Assets committed to this repo and pushed to GitHub are immediately available for linking and reference.

Adding new assets

In accordance with the Flutter style guide, assets submitted to this repository should be easily reproducible, e.g. by running a Flutter app or a script. This makes it easier to update the asset in the future, if needed. Check the existing diagrams (and their generation code) in this repository to see examples. Avoid checking in just a static image file (e.g. PNG, JPEG), without a way to regenerate and update it.

Creating new diagrams

To create a new diagram:

  1. Create a new Dart file inside /packages/diagrams/lib/src/.

  2. Export that file from /packages/diagrams/lib/diagrams.dart.

  3. Create one or more diagram widgets that mix-in DiagramMetadata, overriding the name getter to return their name, which should be lower_snake_case.

    • If your diagram is animated, override the duration getter to return the duration of the animation.

    • If your diagram's state needs to wait imperatively, mix-in LockstepStateMixin and call waitLockstep(duration).

    • If your diagram needs simulated gesture input, acquire a WidgetController by calling DiagramWidgetController.of(context).

  4. Create a class that extends DiagramStep.

  5. Override the diagrams getter of DiagramStep to return a list containing the new diagrams.

  6. Override the category getter of DiagramStep to return the category it belongs in, this corresponds to the folders under /assets.

  7. Add your new DiagramStep to the list in packages/diagrams/lib/src/steps.dart, sorted alphabetically.

  8. Generate assets with bin/generate -s MyDiagramStep, for more options see the generation section.

URL structure

Reference the assets with this URL structure:

https://flutter.github.io/assets-for-api-docs/assets/<library>/<asset>

For example, an image named app_bar.png about AppBar from the material library would go in the assets/material/ directory and be at https://flutter.github.io/assets-for-api-docs/assets/material/app_bar.png.

All asset files should be under the assets directory in an appropriate subdirectory.

Generation

Images must be code-generated.

To create new images, see the packages/diagrams/lib/src/ directory.

The generate.dart script regenerates almost all of existing assets using the Flutter version you have installed. A small wrapper bin/generate (bin\generate.bat on Windows) is provided as a convenience.

To limit image generation to certain categories and/or names, run:

# Filter by category
bin/generate -c cupertino,material
# Filter by name
bin/generate -n basic_material_app,blend_mode
# Filter by step class name
bin/generate -s MaterialAppDiagramStep,BlendModeDiagramStep

bin/generate --help lists available arguments.

Prerequisites

The generate.dart script works on macOS, Linux, and Windows, but it needs several prerequisites in order to run. On Linux and macOS run bin/generate. On Windows, run bin\generate.bat.

To optimize PNG files, it needs optipng, which is available for macOS via Homebrew, and Linux via apt-get, and Windows from the optipng website.

To convert animations into mp4 files, it needs ffmpeg, available for macOS via Homebrew and Linux via apt-get, and for Windows from the FFMPEG website.

Both optipng and ffmpeg need to be in your path when you run the generate script.

flutter, dart (and when using an Android device, adb) commands also need to be available in a directory in the PATH environment variable. (e.g. PATH=~/<path_to_flutter>/flutter/bin/cache/dart-sdk/bin:~/Android/Sdk/platform-tools:$PATH)

When using an Android device, be sure that the adb command is the same as the one running as a server (which is often started by your IDE, so use the same adb the IDE is running).

You cannot currently generate docs on an iOS device (although you can generate them on macOS).

Optimization

Please consider optimization tools for assets.

For PNGs, we recommend optipng, using the following command line:

optipng -zc1-9 -zm1-9 -zs0-3 -f0-5 *.png

Be careful about applying this aggressively. In particular, files in the assets/tests directory should not be optimized.

The automatic generation tool will automatically apply optimization to the assets it generates.

Issues

Please file any issues in the main flutter repo.

Origin of third-party content

More Repositories

1

flutter

Flutter makes it easy and fast to build beautiful apps for mobile and beyond
Dart
157,868
star
2

plugins

Plugins for Flutter maintained by the Flutter team
Dart
17,165
star
3

samples

A collection of Flutter examples and demos
Dart
15,939
star
4

engine

The Flutter engine
C++
6,852
star
5

gallery

Flutter Gallery is a resource to help developers evaluate and use Flutter
Dart
5,866
star
6

packages

A collection of useful packages maintained by the Flutter team
Dart
3,600
star
7

website

Flutter documentation web site
Dart
2,573
star
8

pinball

Google I/O 2022 Pinball game built with Flutter and Firebase
Dart
2,097
star
9

flutter-intellij

Flutter Plugin for IntelliJ
Java
1,906
star
10

codelabs

Flutter codelab examples
C
1,568
star
11

devtools

Performance tools for Flutter
Dart
1,466
star
12

news_toolkit

A news template application built in Flutter, by Google and Very Good Ventures. Learn more at: https://flutter.github.io/news_toolkit
Dart
1,016
star
13

photobooth

Google I/O 2021 Photo Booth built with Flutter and Firebase
Dart
894
star
14

io_flip

Google I/O 2023 FLIP AI-designed card game built with Flutter & Firebase
Dart
597
star
15

flutter_clock

Dart
542
star
16

put-flutter-to-work

A Flutter add-to-app demo you can try with your own apps
Dart
309
star
17

holobooth

Jump into a new reality to bring Dash and Sparky to life!
Dart
230
star
18

tests

Contributed tests for Flutter
Dart
219
star
19

uxr

UXR work for Flutter
Dart
214
star
20

cocoon

Flutter's build coordinator and aggregator
Dart
182
star
21

impeller

Affects Flow
155
star
22

buildroot

Build environment for the Flutter engine
Python
120
star
23

tools_metadata

Metadata files about the flutter framework
Dart
66
star
24

web_installers

Web install scripts for CI for Flutter Web
Dart
42
star
25

goldens

Shell
41
star
26

platform_tests

Tools & tests to verify Flutter's fidelity on specific platforms
Dart
37
star
27

games

Home of the Flutter Casual Games Toolkit and other Flutter gaming templates
Dart
27
star
28

.github

Default community health files for Flutter
26
star
29

flutter-github-scripts.dart

Scripts to facilitate generating reports on the health of the Flutter repositories.
Dart
19
star
30

flutter.github.io

Root of flutter.github.io
HTML
13
star