Cool Flutter Docs

A sign of developer polish and professionalism is being able to have some cool docs generated for your flutter app, plugin, or package. Let me show you how to do that in an easy way.

Pre-Requirements

This is somewhat realy easy as there are only two items to install. First, let’s install the dartdoc tool via your command line:

flutter pub global activate dartdoc

Now, let’s also install an dart http server so that the doc search will work as than you will not get search not accessible errors due to the browser blocking cross scripting. Type this into your terminal:

flutter pub global activate dhttpd

Now, I can configure the dartdoc tool.

Configuring DartDoc

The DartDoc tool will look for a dartdoc_options.yaml file in the root project folder. Now I will show you some of my developer tricks.

When ever you begin learning a new computer language or framework start looking at the internals of the sdk. In Flutter’s case the sdk source is on github. And, if you look you will notice a dartdoc_options.yaml file in it; this one:

I am not going to use some parts of it as I have no processing tools to hook into the doc generation process. But I will use the second part which defines the errors:

I added paths to my favicon and an alternative header to use in generating the api docs.

Generating The Docs

Now to generate the docs type this into your terminal:

dartdoc

gives this output:

And to view it with search working type this into your terminal:

dhttpd --path doc/api

And your api site is viewable at:

http://localhost:8080

It looks like this:

SIDE NOTE: The DartDoc tool will pick up and inject the content of your project’s root readme as content of the index page at the root of the api folder. I have a nice readme site that describes how to properly write a project readme at:

Take some time to emulate it so that you can have polished project readme’s.

And so you can see what happens when the dart httpd server is not running, here is the main dart index page:

Conclusion

Documenting your mobile app api looks polished and makes it easy to see how it works later when you are in the process of maintaining 5 or more mobile apps that you have published. And it’s easier to use this dartdoc tool than some other tools like doxygen.

Resources

Specific to the article: [email protected] https://pub.dev/packages/dartdoc dartdoc_options file@githubFlutterRepo https://github.com/flutter/flutter/blob/master/dartdoc_options.yaml

General Flutter and Dart resources:

Flutter Community Resources https://flutter.dev/community Flutter SDK https://flutter.dev/docs/get-started/install Android Studio IDE https://developer.android.com/studio MS’s Visual Studio Code https://code.visualstudio.com/ Flutter Docs https://flutter.dev/docs Dart Docs https://dart.dev/guides Google Firebase Mobile Device TestLab https://firebase.google.com/docs/test-lab

Trademark Notice

Google LLC owns the following trademarks; Dart, Flutter, Android, Roboto, Noto. Apple Inc owns the trademarks iOS, MacOSX, Swift, and ObjectiveC. Apple Inc owns trademarks to their fonts of SF Pro, Sf Compact, SF mono, and New York. JetBeans Inc owns the trademarks to JetBeans, IntelliJ, and Kotlin. Oracle Inc owns the Java trademark. Microsoft Inc owns the trademarks to MS Windows OS and Powershell. Gradle is a trademark of Gradle Inc. The Git Project owns the trademark to Git. Linux Foundation owns the trademark to Linux. SmartPhone OME’s own trademarks to their mobile phone product names. To the best of my ability I follow the brand and usage guidelines with the above mentioned trademarks.

About Fred Grott

I’m the crazy SOB who as a former android mobile developer is starting to write about flutter mobile app development, design, and life(see Eff COVID and GOP https://fredgrott.medium.com/eff-covid-and-the-gop-e912db0548b8). Will I reach the pivotal One Million Medium monthly viewers mark? Sit-back and watch it happen. Find me on these social platforms:

https://twitter.com/fredgrott