Thanks to a helpful comment on last night's work, I now know that
dartdocis part of the standard Dart SDK. Indeed, had I checked the contents of the SDK that I downloaded yesterday, I would have seen it amongst the other Dart goodness:
➜ src unzip -l ~/Downloads/dart-linux\ \(3\).zip | grep dartdoc 0 2012-03-19 17:31 dart-sdk/lib/dartdoc/ 2295 2012-03-19 17:31 dart-sdk/lib/dartdoc/utils.dart 3856 2012-03-13 13:15 dart-sdk/lib/dartdoc/comment_map.dart 1096 2012-03-13 13:15 dart-sdk/lib/dartdoc/client-shared.dart 38064 2012-03-25 16:24 dart-sdk/lib/dartdoc/dartdoc.dart ...I unzip that into
$HOME/src(that's where I store source code that is not under SCM). Then I try generating
dartdocfor Hipster MVC:
➜ hipster-mvc git:(master) ✗ dart ~/src/dart-sdk/lib/dartdoc/dartdoc.dart Hipster*dart Unknown option: HipsterCollection.dartBummer. It seems that
dartdoconly accepts a single argument—anything else is treated as an option.
If I generate documentation for
HipsterRouter(which depends on
HipsterHistory) and then
HipsterView(which depends on
HipsterModel), it seems to work:
➜ hipster-mvc git:(master) ✗ dart ~/src/dart-sdk/lib/dartdoc/dartdoc.dart HipsterRouter.dart Documented 5 libraries, 665 types, and 5480 members. ➜ hipster-mvc git:(master) ✗ dart ~/src/dart-sdk/lib/dartdoc/dartdoc.dart HipsterView.dart Documented 8 libraries, 672 types, and 5531 members.But, of course, I have overwritten the results from my first run with my second, leaving me no documentation for
This will not do.
To get around this, I create an
index.dartfile that contains nothing other than imports of my two highest level classes:
#import('HipsterView.dart'); #import('HipsterRouter.dart');When I run
dartdocagainst that, it seems to pick up the correct number of libraries:
➜ hipster-mvc git:(master) ✗ dart ~/src/dart-sdk/lib/dartdoc/dartdoc.dart index.dart Documented 11 libraries, 677 types, and 5544 members.Unfortunately, "index" was probably a poor choice as this seems to have resulted in an overwritten
So I rename that to
main.dart(even though there is no
main()entry block) and regenerate my documentation:
➜ hipster-mvc git:(master) ✗ dart ~/src/dart-sdk/lib/dartdoc/dartdoc.dart main.dart Documented 11 libraries, 677 types, and 5544 members.That seems to have done the trick:
Local documentation does not do much good. I need some way to get that information up to the github repository. At first I try pushing the HTML docs into the wiki, but that has no effect. The wiki tab only houses wiki pages written in one of the various github recognized markups.
So it seems that I need to use github's other documentation vehicle: github pages. To create the github pages, I follow along with the github pages instructions:
➜ hipster-mvc git:(master) ✗ mv docs /tmp/hipster-mvc-docs ➜ hipster-mvc git:(master) git symbolic-ref HEAD refs/heads/gh-pages ➜ hipster-mvc git:(gh-pages) ✗ rm .git/index ➜ hipster-mvc git:(gh-pages) ✗ git clean -fdx Removing .gitignore Removing HipsterCollection.dart Removing HipsterHistory.dart Removing HipsterModel.dart Removing HipsterRouter.dart Removing HipsterSync.dart Removing HipsterView.dart Removing README.asciidoc Removing wiki/ ➜ hipster-mvc git:(gh-pages) ✗ mv /tmp/hipster-mvc-docs/* . ➜ hipster-mvc git:(gh-pages) ✗ git add . ➜ hipster-mvc git:(gh-pages) ✗ git ci -m "dartdoc generated HTML" -a [gh-pages (root-commit) 3364e2a] dartdoc generated HTML 703 files changed, 107930 insertions(+), 0 deletions(-) create mode 100644 body-bg.png create mode 100644 class.png ... ➜ hipster-mvc git:(gh-pages) gp origin gh-pagesWith that, I have my Hipster MVC API documentation. There is still much work to be done to whip that into a consumable state, but this is a pretty good start.