This repo contains a package and a Flutter app meant to help Flutter framework developers (the developers that work on the framework itself) create sample applications for the API documentation for Flutter.
To run the app, run the appropriate executable for your platform, under the bin directory.
This will run a Flutter app that will automatically load the list of files in the framework, and let you pick one.
If the the flutter command is on your PATH, the app should be able to find the
repo automatically, but if not, or if you'd rather specify the location yourself,
you can either set the FLUTTER_ROOT environment variable, or supply the
--flutter-root argument to the executable with the absolute path to the
flutter repo you wish to use.
If you want to add a new sample, add a blank insertion into a dartdoc, like this, before you select the file in the app:
/// {@tool dartdoc --template=material_scaffold}
/// {@end-tool}
Also before you select a file in the app, if you want to change the template you are inserting into, change it in the original dartdoc comments before you extract.
When the app starts, type part of the name of the file in which you would like to edit a sample, and it should autocomplete. Select the file, and it will show you a list of the available samples to edit.
Once you select a sample with the SELECT button, it will move to a detail page
where you can extract that sample into a temporary project, and open the project
in an IDE or editor.
Now you can extract the sample with the EXTRACT SAMPLE button, it will create
a temporary project and prepare it for editing. Be sure you have your
Flutter git repo in the correct branch/state for editing the files you want to
edit.
Once you have extracted the sample, you can copy the path to its main and open
that in your editor, or use the OPEN IN VS CODE or OPEN IN INTELLIJ buttons
to open then project in an IDE.
Now you can edit that sample. Be careful to only edit the sections inside the section markers: any editing occurring outside the section markers will be lost when the code is reinserted. If you need to make a change to code that is not part of a section, you will have to edit the template, or create a new template, instead.
Here's what the section markers look like:
//********************************************************************
//* ▼▼▼▼▼▼▼▼ code ▼▼▼▼▼▼▼▼ (do not modify or remove section marker)
//[ code goes here ...]
//* ▲▲▲▲▲▲▲▲ code ▲▲▲▲▲▲▲▲ (do not modify or remove section marker)
//********************************************************************
After you're done with your modifications to the sample, save the code to disk,
and then go back to the sampler app. You can then click the REINSERT button
to take the edited sample and it will be placed back into the documentation
comments in the original framework file. You can open that file from the
sampler app with the appropriate buttons, or copy/paste the path into your
editor.
This is still a work in progress, so if you find something missing, either send me a PR, open an issue, or just message me.
Some features I'm planning to add:
- Creating a new sample on an element in a file.
- Change the template that a sample is inserted into and re-export.
- Persistent settings for:
- The location for your editor/IDE
- The location of the Flutter repo to use
- The location for the temporary projects
- Cleaning up the temporary projects after re-insertion.
- More tests!
- Converting Flutter's CI sample analysis and snippet tools to use the snippets package herein (maybe).
- How best to distribute to the team? Prebuilt binaries seem...clunky, and building it yourself even more so.