add doclets.io config (automated JSDoc pages)

[lipp]

Adds documentation to doclets.io service. Future tags and master branch will be published automatically.

Preview generated with my account

@caolan If you like this, you are very welcomed to login to https://doclets.io with GitHub OAuth. If you don't like it, I'd be happy to hear what you don't like about it :)

Steps required (3min):

1. @caolan logs in to doclets.io
2. @caolan adds async
3. someone merges this PR

Resolves #1083

[aearly]

A cool little service. @caolan would have to be the one to set it up, since he owns this repo.

We're planning on doing the JSDoc parsing ourselves and setting up the site on http://caolan.github.io/async

[caolan]

Looks pretty, but I don't see that it adds much in return for including another third party and spreading our documentation links more thinly. Adding a github pages version of the docs is preferable to this, and is compelling if it's used to include more interactive examples.

-1 on doclets.io

[lipp]

@caolan Thanks for your feedback. Actually, interactive examples are supported:
https://doclets.io/lipp/async/add-to-doclets#dl-async-reduce

I can understand your concerns regarding the "spreading" and the "3rd party bloat".
At the end it "costs" you 3 lines of yml code which eventually save you a lot of time.

@aearly @caolan Thanks again for your time and your precious feedback!

BTW: async is just an awesome project (doclets is using it of course)! Thanks for providing and constantly improving it!

[megawac]

I actually really dig this assuming it has all the features I was looking for:

• Are categories or type tags supported to define subsections?
• How do you reference other methods, see do doUntil referencing doWhilst
• We would have to change our @see references
• can the generated jsdoc be exported?

Is it fine if we point a domain to this. I recently purchased http://asyncjs.xyz for $1/y in case we wanted to use it. Otherwise I think we should probably just generate them ourselves

[megawac]

Also is is possible to include a javascript file that will be exposed to a clients console. I would want to have async.js loaded and the async variable exposed in whatever solution we use

[lipp]

@megawac The links work if a) backticks are removed b) @link jsdoc is used as documented (see commit and http://usejsdoc.org/tags-inline-link.html).

The @category tag is not part of JSDoc, but as many projects are using it anyways I'll add support for it.

[lipp]

As awful as it sounds but may including the doclets page through iframe be an option? The "theme" will be very minimal removing most colors (or make them editable).

This way the doc pages stay "fresh" (webhooks) and get continuously improved as doclets improves.

[megawac]

@lipp you mentioned (on pug) it might be possible in the future for the service to publish to gh-pages? If that was the case what would be the real benefit of your service over generating them ourselves?

Also did you see my earlier message?

Also is is possible to include a javascript file that will be exposed to a clients console. I would want to have async.js loaded and the async variable exposed in whatever solution we use

I am quite open to using your service as we haven't committed to a jsdoc scheme yet (#1083)

[lipp]

@megawac pushing to the gh-pages could be an option for overcoming the domain/self-hosting issue. I am not sure yet, what is the best solution for "embedding" the doclets content.

No matter which "embedding/push" mechanism will be employed, the point of doclets is, that the docs are auto-generated with every push and for all tags/releases. This is much like continuous integration for API docs. Once doclets is enabled, the authors shouldn't care about re-generating docs, link to new versions etc.

As a plus, when doclets gets new features (improved search, navigation, etc) the respective API doc will be "updated" too, since the doc pages are rendered using the "raw jsdoc" data.

Loading a custom script ( script tag + url) would be possible (which would enable libs/modules to be available on console. However, I don't see the advantage over embedding examples through Tonic or jsFiddle. Could you elaborate on the advantages using the console please?

Regards and many thanks for the feedback!

[megawac]

Loading a custom script ( script tag + url) would be possible (which would enable libs/modules to be available on console. However, I don't see the advantage over embedding examples through Tonic or jsFiddle. Could you elaborate on the advantages using the console please?

@lipp its nice to be able to load up your console and interact with a library with native autocomplete features and standard debugging tools. For instance, whenever I'm experimenting with lodash/ramda/underscore methods I usually will do it in my console. I usually prefer my console to those interactive tools but having both are nice (like in the ramda docs)