improve discoverability of http://www.dartdocs.org/failed/

[devoncarew]

I don't see docs for spark_widgets. It's up on pub. Does it not have the right entry-point? Or was there a failure running dartdoc? It would be nice to be able to get some feedback when there are issues. Perhaps a separate /status page per package? It could have diagnostics about the last n compiles.

[adam-singer]

Generally the page http://www.dartdocs.org/failed/ is supposed to represent the failed builds. Its not discoverable from the root page which is bad. Need to fix that. What specifically is wrong with spark_widgets can be seen at this build log http://www.dartdocs.org/buildlogs/b-fd853252a46fab2b1118c5bf46314-startupscript.log

17:46:10-adam@Adams-MacBook-Air:~/bin
$ pub cache add spark_widgets
Downloading spark_widgets 0.0.2...
17:46:17-adam@Adams-MacBook-Air:~/bin
$ cd ~/.pub-cache/hosted/pub.dartlang.org/spark_widgets-0.0.2
17:46:20-adam@Adams-MacBook-Air:~/.pub-cache/hosted/pub.dartlang.org/spark_widgets-0.0.2
$ ls
LICENSE      README.md    example      lib          pubspec.yaml test
17:46:20-adam@Adams-MacBook-Air:~/.pub-cache/hosted/pub.dartlang.org/spark_widgets-0.0.2
$ ls lib
common               spark_menu           spark_modal          spark_split_view     spark_toggle_button
spark_button         spark_menu_button    spark_overlay        spark_splitter       spark_toolbar
spark_icon           spark_menu_item      spark_selection      spark_status         spark_tree_view
spark_icon_button    spark_menu_separator spark_selector       spark_suggest_box

I'm not sure docgen can support that format with no dart files in the lib folder.

Also want to create a history view, so its easy to page the history of builds. All the information is there just need to expose it from datastore.

[adam-singer]

also the formatting of the failed page is not great for package authors. Package authors are the ones who will most likely want to see which packages of theirs fail.

[devoncarew]

OK, I'll update this issue to reflect that the failed page needs to be a bit easier to find.

I'm not sure docgen can support that format with no dart files in the lib folder.

Do you know, do people generally work around this issue by adding a single entry-point into lib/? So, something like lib/spark_widgets.dart that reference (and export) all the other libraries. (cc'ing @ussuri)

[adam-singer]

One way would be to have lib/spark_widgets.dart with import/export statements, that would appease docgen without additional configurations. Just tested https://github.com/dart-lang/spark/pull/2004 and it generates docs without any problems . Downside is the library file will have a lot of unused warnings from the import statements. Without the import docgen will barf.

The other way is having custom shell scripts that pick off the entry points based on convention of the project. For example Pixelate does this. This doesnt help with dartdocs...

I think a good option would be to make docgen have a configuration driven command line option. I thought I had a bug on dartbug on this.. Cant find it now. Something like docgen --config docgen.json which would look something like

{ 
  "options": ["compile", "no-include-sdk", "no-include-dependent-packages", "include-private"],
  "out": "docs",
  "dart-sdk": "/dart-sdk",
  "package-root": "./packages",
  "dart-libraries": [list of entry points to document]
}

relevant issue: https://code.google.com/p/dart/issues/detail?id=18554

I'm actually not crazy about the options file, but until polymer/angular and other components of a package are easy to document I think its a good option.

[ussuri]

Thanks a lot for all the explaining, @financeCoding ! It looks like a single entry point is the more achievable approach right now. I think it's ok if it generates warnings, as most devs don't usually pay attention to errors/warning in the included libraries. Does anyone of you know if there are plans to add some kind of warning/error control to Dart, along the lines of C++'s #pragma?

[adam-singer]

@devoncarew http://www.dartdocs.org/ should now contain a link to the failed packages. The failed packages page could look much better. Closing this out.