Publishing Dartdoc to Github

‹prev | My Chain | next›

Thanks to a helpful comment on last night's work, I now know that dartdoc is 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 dartdoc for Hipster MVC:

➜  hipster-mvc git:(master) ✗ dart ~/src/dart-sdk/lib/dartdoc/dartdoc.dart Hipster*dart          
Unknown option: HipsterCollection.dart

Bummer. It seems that dartdoc only 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 HipsterCollection and 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 HipsterRouter or HipsterHistory:

This will not do.

To get around this, I create an index.dart file that contains nothing other than imports of my two highest level classes:

#import('HipsterView.dart');
#import('HipsterRouter.dart');

When I run dartdoc against 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 index.html file:

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-pages

With 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.

Day #337