Support dartdoc --include option for API doc generation

[chalin]

A package's pubspec documentation entry could support an include entry; e.g.

documentation:
  url: optional-url
  include: optional-list-of-libs

This is motivated by

• https://github.com/dart-lang/site-webdev/issues/1440
• Remove all of the extra libraries... angulardart/angular_components#242

cc @kevmoo @kwalrath @nshahan

[nshahan]

Would an exclude be feasible as well?

[chalin]

Probably makes sense to implement both. On the webdev site we currently only use include, but we did, at some point, need exclude as well.

[kevmoo]

CC @jcollins-g

Anything done here should coordinate w/ the new dartdoc_options.yaml

dart-lang/dartdoc@44dfb15

[jcollins-g]

I'm going as fast as I can to support all applicable dartdoc command line flags in dartdoc_options.yaml. I'm two PRs away from the initial support for this. Please file bugs on dart-lang/dartdoc for parameters and use cases that are important.

[isoos]

I'm a bit sad that Dart is getting more-and-more separate config files (pubspec.yaml, analysis_options.yaml, build.yaml) and now dartdoc_options.yaml. Is there at least a plan to make the work under a single one?

[kevmoo]

Separation of concerns is good, I think. It'd be worse if we had to coordinate all of these files in one place.

…

On Wed, Apr 18, 2018 at 8:29 AM István Soós ***@***.***> wrote: I'm a bit sad that Dart is getting more-and-more separate config files ( pubspec.yaml, analysis_options.yaml, build.yaml) and now dartdoc_options.yaml. Is there at least a plan to make the work under a single one? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1216 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AABCio4sevoWbTexZG2M9ElSJlyBvsT1ks5tp1vmgaJpZM4TYiiP> .

[isoos]

I don't see much need for coordination when putting these under pubspec.yaml (besides the trivial agreement on the top-level key), after all Flutter does store some of its config there too. (Please don't tell me that those will be under a different file too...)

[chalin]

Please file bugs on dart-lang/dartdoc for parameters and use cases that are important.

@jcollins-g: can you give me a base issue # that I can refer to? Btw, do you already have support for include / exclude options covered in one of the already opened issues?

[jcollins-g]

@isoos There is no current plan to unify them. The name of the file and the top-level key is fairly mutable still for dartdoc (almost noone uses the current, limited functionality) but that's going to change very rapidly if I get my way.

@chalin There is one now: dart-lang/dartdoc#1674. I'm already planning to support many command line options including those, but if there's a particular use case (e.g. a command line you'd really prefer to be in a config file) I can make sure that happens.

[jakobr-google]

We are assuming this will be handled by dartdoc

[jcollins-g]

dart-lang/dartdoc#1700 adds (tested and working) support for include/exclude in dartdoc_options.yaml.

[kevmoo]

Sweet!

…

On Wed, May 30, 2018 at 8:07 AM jcollins-g ***@***.***> wrote: dart-lang/dartdoc#1700 <dart-lang/dartdoc#1700> adds (tested and working) support for include/exclude in dartdoc_options.yaml. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1216 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AABCigcNmJmu_KaJd_dg6iOKml50pWEpks5t3rWsgaJpZM4TYiiP> .

[chalin]

@isoos - has pub docs been setup to use this new functionality yet?

[isoos]

has pub docs been setup to use this new functionality yet?

If dartdoc picks it up from the package archive, it should work, we don't actively prevent it. The current online version is using dartdoc 0.20.0.

[isoos]

Due to security concerns we have disabled dartdoc_options.yaml(by deleting it before dartdoc is being run) a while back, and it is no longer and for the foreseeable future we are not going to enable it again. If/when we move the generated docs to a new domain we might consider enabling specific options (separately), please open new issues if you want us to support one or more of them.