`ember serve --docs` doesn't work for ember-cli >= 0.2.4

[akatov]

trafficstars

ember serve --docs works with ember-cli up to version 0.2.3, but not with version 0.2.4 or higher. It still starts up regularly and starts preparing the documentation, but doesn't recognise the /docs URL any longer.

ember ember-cli-yuidoc still works fine.

[akatov]

@cibernox any idea about this?

[raido]

Any updates? Does not work with ember-cli 1.13.6 either.

[offirgolan]

For a quick fix, create the file <APP_ROOT>/server/index.js and put this in there

module.exports = function(app) {
  app.get('/docs', function(req, res){
    res.redirect('/docs/index.html');
  });
};

[akatov]

actually, as of ember-cli 2.8.0, the problem seems to be that I set locationType to 'auto' in my config/environment.js. Once I set it to 'hash' or 'none' the development server serves the documentation build under docs rather than trying to resolve it with the Ember Router first. @cibernox do you think having a serverMiddleware would make ember serve --docs work even with locationType set to 'auto'? Or is there another way of telling Ember to ignore certain routes?

[akatov]

Btw, another consequence of serving files directly is that the URL has to be the same as defined in yuidoc.json's options.outdir. I.e. if I change it to doc rather than docs, then I have to access the live documentation build under /doc rather than /docs. @cibernox do you think this is reasonable behaviour (in which case it's probably worth mentioning it in the README), or should ember server --docs always force the documentation URL to simply be /docs (this would especially make sense if we used a middleware rather than serving files directly).

[akatov]

@cibernox do you think it makes sense to close this issue and open a new one (or two) with more appropriate titles in light of my last two comments?

[dephora]

Any updates on this?

If it was addressed, I'm still having issues accessing /docs when serving with ember serve --docs (as well as receiving warnings of --docs not being registered with ember serve.

Ember 2.11

[buschtoens]

For the time being just go to http://localhost:4200/docs/index.html.

[cibernox]

I must confess that I don't use this addon anymore and I don't have time/energy to maintain it.

If anyone who is actively using it wants to take over its maintenance I can give permissions or transfer the repo.

[buschtoens]

Thanks for letting us know and thanks for all the hours you have poured into this add-on.

Out of curiosity, are you using a different add-on now or just don't need to doc anymore?

I'm asking because just today or company decided to use this add-on to document our code base. :sweat_smile:

@offirgolan might have a legit interest in keeping this add-on alive and well. :)

[cibernox]

I not longer have to maintains docs of the code. I've continued to merge PRs but I think it would be better maintained by someone who actually dogfoods his own work.

[dephora]

Yes, definitely appreciate the time and effort put into this. I too am curious about documentation choice. I have no allegiances, I initially started with jsdoc but when I saw that ember core uses yui, I decided to switch to that.

[cibernox]

My little secret is that today, if I had to document a library, I'd go right away and use typescript. Support for typescript in addons is not perfect but I want to improve the situation as soon as I have some free cycles. Documentation tends to fall behind in completeness and accurateness as time passes, independently of the syntax you use. I came to believe that the only way of keeping docs in sync with the code is if docs are extracted from it.