CP-924 New Task: documentation generation via dartdoc.

[evanweible-wf]

Issue

#26 To round out the suite of tasks available, documentation generation should be included.

Changes

Source:

• Add a docs task that uses dartdoc to generate documentation
• The defaults for documentation generation should be fairly standard, so for now, there are no configuration options
• The CLI has an --open flag that defaults to true but can be negated. This flag controls whether or not the generated docs should be opened automatically.

Tests:

• Two integration tests added for the docs task.

Areas of Regression

• n/a

Testing

• Verify that the docs task successfully generates and opens documentation
  • ddev docs
  • doc/api/ created
  • doc/api/index.html opened automatically in browser
• Verify that the docs are not opened automatically when --no-open is set
  • ddev docs --no-open
  • doc/api/ created
  • doc/api/index.html not opened
• Verify that the task fails with explanation when the dartdoc package is not an immediate dependency
  • remove dartdoc from pubspec.yaml
  • ddev docs
  • verify failure with explanation

Code Review

@trentgrover-wf
@maxwellpeterson-wf
@dustinlessard-wf
@jayudey-wf

[evanweible-wf]

If you're curious, here's what some docs generated by dartdoc look like now:

Definitely a big improvement over the old docs. Also, this is only using dartdoc v0.4.0, but they're about to cut 0.6.2. The versions beyond 0.4.0 require dart 1.12 though.

[dustinlessard-wf]

+1 Looks great!

[maxwellpeterson-wf]

+1

Looks like format needs to be run on this.

[evanweible-wf]

@maxwellpeterson-wf fixed.

[codecov-io]

Current coverage is 48.05%

Merging #58 into master will not affect coverage as of 533716e

Powered by Codecov. Updated on successful CI builds.

[maxwellpeterson-wf]

+1

[trentgrover-wf]

+1
@jayudey-wf ready for merge

[jayudey-wf]

QA Resource Approval: +10

• Testing instruction
• Dev +1's
• Dev/QA +10 with detail of what was tested
  • installed branch into state_machine, verified:
  • command worked as expected and opened docs in browser
  • when command was run with --no-open the docs page was not opened in the browser
  • if dartdoc was not a dependency then task failed with a helpful message
• Unit test created/updated
• All unit tests pass

Merging into master.

[evanweible-wf]

fyi @rayk - documentation generation via the dartdoc tool has been added to dart_dev, should be included in the next release

[jayudey-wf]

@Rosie run_merge_script