ember-cli-addon-docs

[ro0gr]

I like an idea to leave documentation concerns to another cool community tool.

https://ember-learn.github.io/ember-cli-addon-docs/

From the main page:

• Show current and versioned guides, ideally whose content is verified by automated tests
• Show current and versioned API documentation derived from structured comments in source code
• Make it easy for contributors to correct documentation errors in addition to submitting code fixes

[ro0gr]

Sorry. Not this time.

According to ember-learn/ember-cli-addon-docs#2 versioned docs is not implemented yet

[san650]

YES! let's do it

[mistahenry]

To use Addon Docs, your addon must have a devDependency of Ember v2.8 or higher.

Note that your addon can still support older versions of Ember – it's just that you won't be able to run your Addon Docs documentation site against those older versions. (This means you also cannot write acceptance/application tests against your docs sites on older versions of Ember.)

Since this addon currently has an ember-lts-2.4 ember-try scenario, it's worth discussing before anyone attempts to implement. Either drop 2.4 or run no acceptance tests against the docs (which doesn't seem like a good idea).

[ro0gr]

I believe we are more coupled to the test-helpers rather than Ember.

We can keep running acceptance tests for all the Ember versions, as we do now, while testing of the guide examples against the supported(by addon-docs) versions of Ember.

[mistahenry]

I believe we are more coupled to the test-helpers rather than Ember.

The addon docs leverage the test's dummy app directly, which uses the addon's devDependency ember version. Ember cli addon docs uses contextual components which locks you into 2.3+. If you look at this closed issue you can see the discussion. But they set the explicit support at 2.8+.

During Ember try, if we continue to have a 2.4 scenario, our acceptance test for 2.4 does not fit ember-cli-addon-docs's support matrix, which IMO is a risk worth discussing before implementing this feature.

As far as I see it, the reasonable options are:

1. Drop support for ember-lts-2.4
2. Some explicit filter scheme that excludes the docs + their tests from the ember 2.4 scenario, which I imagine would not be trivial to implement.
3. Hope that despite explicit support, the 2.4 tests will work just fine (which they did in a test I just ran)

[ro0gr]

Ember cli addon docs uses contextual components which locks you into 2.3+.

That's true only in case if you visit the page which uses contextual components.

Drop support for ember-lts-2.4

I hope, we wouldn't allow docs tool to dictate us support matrix limits 😆

Some explicit filter scheme that excludes the docs + their tests from the ember 2.4 scenario

I think we can simply mark tests related to addon-docs by some tag, e.g.:

module('[docs] Page 1', ....)

Then we just need to customize the ember-try scenario for ember@2.4 to use QUnit filter, which excludes the docs tests:

  command: 'ember test --filter ![docs]',

This way we wouldn't run the tests which depends on addon-docs for ember@2.4 scenario only.

[mistahenry]

These were just the options, not ranked in order of most reasonable ;)

I agree that 2 is the right way and seems easier than I presumed it might be. I've been wanting to play with the addon docs lib so whenever this next release with updated documentation happens, I'd be happy take a stab at it

[ro0gr]

That sounds exciting!

[ro0gr]

The other intriguing question to me is what are our options to host the new docs. Should we preserve the old guides with some clever redirect mechanism(for SEO) or is it possible to migrate the old guides content to the new guides and preserve the URL structure.

I believe a working stab can unlock us to experiment with what addon-docs does allow us to achieve in this area..

[rtablada]

Update on this http://www.ember-cli-mirage.com/ switched from old versioned jekyll docs to Ember-CLI-Addon-Docs and @samselikoff discussed some of the process on the recent EmberMap Podcast.

I know there were definitely hurdles to get over, but it is doable and I think would really help make the docs more unified with the Ember community of other addons and allow more people to contribute

[mistahenry]

I'll try to find sometime in the next week to start the process. Where's the best place to hear that podcast @rtablada?

[rtablada]

@mistahenry https://embermap.com/podcast/mirage-meet-addon-docs

[mistahenry]

started here: https://github.com/mistahenry/ember-cli-page-object/tree/enhancement/addon-docs

[ro0gr]

The addon docs leverage the test's dummy app directly, which uses the addon's devDependency ember version. Ember cli addon docs uses contextual components which locks you into 2.3+. If you look at this closed issue you can see the discussion. But they set the explicit support at 2.8+.

I think it should be solved by ember-learn/ember-cli-addon-docs#409