-
Notifications
You must be signed in to change notification settings - Fork 2.4k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
add doclets.io config (automated JSDoc pages) #1135
Conversation
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 https://caolan.github.io/async |
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 |
@caolan Thanks for your feedback. Actually, interactive examples are supported: I can understand your concerns regarding the "spreading" and the "3rd party bloat". @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! |
I actually really dig this assuming it has all the features I was looking for:
Is it fine if we point a domain to this. I recently purchased https://asyncjs.xyz for $1/y in case we wanted to use it. Otherwise I think we should probably just generate them ourselves |
Also is is possible to include a javascript file that will be exposed to a clients console. I would want to have |
use jsdoc conformin @link inline tag
@megawac The links work if a) backticks are removed b) @link jsdoc is used as documented (see commit and https://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. |
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. |
@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?
I am quite open to using your service as we haven't committed to a jsdoc scheme yet (#1083) |
@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! |
@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) |
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):
Resolves #1083