June 21, 2020
Flutter: Dart Doc
This article is almost completed but not completed. So, it’s a draft article.
To know how the dartdoc looks like you should open this documentation of URL Launcher. This documentation is created using
dartdoc and all this was build because the developer followed the dart recommended way comment.
Installing dartdoc #
- download the Dart SDK
- add the SDK’s bin directory to your PATH
You can read about Dartdoc Package. This comes with Dart which means we don’t need to install this manually.
All these are features of dart and if dart is not instead in your machine then this all will not work.
Verifying dartdoc installation #
If you not sure if the dartdoc is installed in your machine or not.You can verify by checking the version number on dartdoc.
If it’s not installed then then you will get some error message, if it’s installed you will get version number like this.
$ dartdoc --version dartdoc version: 0.30.3 $
Generation documentation #
To generate the documentation you should open your flutter/dart project and write this command.
$ dartdoc Documenting dartdoc... Initialized dartdoc with 766 libraries in 63.9 seconds Generating docs for library dartdoc from package:dartdoc/dartdoc.dart... Validating docs... no issues found Documented 1 public library in 17.9 seconds Success! Docs generated into <path to dartdoc>/doc/api $
By default, the documentation is generated to the doc/api directory as static HTML files.
If you provide some flag with the
dartdoc command then it will generate the documentation based on that.
These flags are important and you might not in most cases. You should learn about these flags before building the final documentation.
Adding flags while running the command has one common issue that we need to write the flag all the times. Sometimes we forget some flag also.
To solve this problem we have
dartdoc_options.yaml where you defined all the flag value and it will take all the values from there.
Adding flag to the dartdoc #
This is very long flag and I know it’s difficult to write all the time. Let’s copy this time for doing this task repetitively there is a solution in next step.
The exclude flag is used to exclude the documentation of following package. Now we’ll not have the documentation of all these package which we had specified.
$ dartdoc --exclude dart.collection,dart.math,dart.core,dart.io,dart.ui,dart.convert,dart.async Documenting dartdoc... Initialized dartdoc with 766 libraries in 63.9 seconds Generating docs for library dartdoc from package:dartdoc/dartdoc.dart... Validating docs... no issues found Documented 1 public library in 17.9 seconds Success! Docs generated into <path to dartdoc>/doc/api $
I took this file from the README.md file of dartdoc. This is just example file not the recommend configuration. You should make your own file based on your package.
Once you mention all the flags value then next time whoever is building the documentation don’t need your help for flag. They know the flags and
doctdoc also knows the flag.
dartdoc: categories: "First Category": markdown: doc/First.md name: Awesome "Second Category": markdown: doc/Second.md name: Great categoryOrder: ["First Category", "Second Category"] examplePathPrefix: "subdir/with/examples" includeExternal: ["bin/unusually_located_library.dart"] linkTo: url: "https://my.dartdocumentationsite.org/dev/%v%" showUndocumentedCategories: true ignore: - ambiguous-doc-reference errors: - unresolved-doc-reference warnings: - tool-error
Viewing docs locally #
Our doc is static file and it can be directly open the browser. Our doc have search functionality but that will not work without http server.
There are various possible way of doing this:
- Dart (recommended)
I recommend Dart way because I don’t how many of you are familiar with other programming language and which language is installed in your machine.
If you have any
http server package/
web serveris installed then you can use it
An easy way to run an HTTP server locally is to use the
$ pub global activate dhttpd $ dhttpd --path doc/api
I think it’s very slow in the terms of speed but we can manage once. We don’t generate the documenting all the time. We don’t update the documentation very frequently. Generating decimation is not very once or twice a month thing.
I like this features but I hate one thing that I need to set the path of flutter. Dart should do some magic and find it by itself. I also like other thing which is we have ability to some kind of customization.
Read the DartDoc Readme file, you will find lots of things there but I know everybody don’t likes boring readme file. But I you would like to learn more I totally recommend seeing Readme file. I learned almost all the things about this from there.