Adding docs-page blueprint.

[scalvert]

Wanted to push up this WIP PR that adds blueprint support for adding a docs page.

I've been on a bit of a tear updating all my addons to use ember-cli-addon-docs, and I absolutely love it. One thing that feels like it's missing though is a blueprint for adding a docs page. I want it to be able to

• Add the markdown file under docs
• Update the router with my docs page route
• Add the {{nav.item ...}} to the docs.hbs (if it exists)

Sample usage:

ember g docs-page foo-bar-baz

Generates:

installing docs-page
  create tests/dummy/app/templates/docs/foo-bar-baz.md
updating router
  add route foo-bar-baz

Docs update:

[pzuraq]

I'm definitely plus one on this, seems like it could help cut down on a lot of boilerplate work 😄

[scalvert]

I was starting to write some nice tests for this functionality using ember-cli-blueprint-test-helpers, which has some nice helpers to create new addons/test blueprints. Unfortunately, that package uses mocha/chai, and the node tests in this repo use QUnit.

I'm open to still adding tests, but will have to do a bunch of fandangling to make it work. Thoughts on the importance of adding tests for this blueprint, @dfreeman, @samselikoff, @pzuraq? (I have guilt just asking that...).

[samselikoff]

I think I'm ok with merging this for now, @pzuraq @dfreeman?

I think ultimately it'd be great to get a filesystem-based solution perhaps with some frontmatter on docs pages that would do most of this automatically for us. But I think this is a great first step to improving the experience.

[samselikoff]

Could you document the generator somewhere?

[scalvert]

Absolutely. I’ll add to the docs.

[dfreeman]

Agreed that it's probably fine to go ahead and merge this—if it does break, at least it won't bring down people's documentation. Thank you for proposing this, @scalvert!

Separately, we might want to consider migrating our node tests to mocha at some point, since that's more aligned with what most projects are using for that.

[scalvert]

@dfreeman if a port to mocha does proceed, I'll circle back and add tests for this blueprint. They're fairly trivial to add once I can use the existing test packages.

[pzuraq]

I'm +1 on merging this for now, haven't had time to review in depth but I trust y'all, and like @dfreeman said it won't break existing things 😄

[scalvert]

OK @samselikoff, I've added docs via the Quickstart. When the directions call for adding the index and usage routes, I prompt the usage of the blueprint. Let me know if that works.

[scalvert]

BTW, I would have use ember-template-recast to do the nav item adding, but that package does some odd things with whitespace and node replacement. I opted to use quick-n-dirty file line manipulation. It ain't pretty, but it gets the job done.

[scalvert]

I'm just going run through some manual testing of the blueprint prior to you merging. I'll ping back here once I've ensured everything is generated in the right way.

[scalvert]

OK, tested out the following scenarios:

Non-pods:

• Generates markdown doc in correct directory, with correct name and template content
• Generates route entry in router.js
• Generates nav item in docs.hbs, if present

Pods:

• Generates markdown doc in correct directory, with correct name and template content
• Generates route entry in router.js
• Generates nav item in pods/docs/template.hbs, if present

These will form the basis for tests if updated to mocha for node tests, as @dfreeman suggested.

[scalvert]

@dfreeman @pzuraq @samselikoff this is good to merge once CI passes.

I'll circle back on the testing front in a subsequent PR.

[samselikoff]

You rock brotha! Nice work 🤙