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.

Customization

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.

  • favicon
  • rel-canonical-prefix
  • pretty-index-json
  • header
  • footer-text
  • footer
  • exclude

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
$

dartdoc_options.yaml

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_options.yaml 
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)
  • php
  • node
  • python

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 server is installed then you can use it

An easy way to run an HTTP server locally is to use the dhttpd package.


$ pub global activate dhttpd
$ dhttpd --path doc/api

Conclusion

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.