Thanks for the walkthrough, Scott! I understand that much of this is proof-of-concept, but it's still highly useful. I'll take a look through your samples.
On Wednesday, 29 January 2014 17:19:02 UTC, Scott Miles wrote: > > For documentation, we have a system today that leverages YuiDoc tooling > and a context-free documentation syntax. The output we consume is a JSON > database, which can be rendered statically or on demand. > > An example of some rendered documentation can be seen here: > http://polymer.github.io/three-js/components/three-js/ > > The documentation renderer used is a component (polymer-doc-viewer) . The > default landing page (which includes the docs) is generated by another > component (polymer-home-page). > > Yes, the actual database is for `webaudio-knob` while the page is supposed > to be about `three-js`, that's just me being sloppy. I wasn't planning on > sharing these materials exactly today, but since it came up ... =P > > Now, this example is a bit half-baked for a couple of reasons: (1) we are > evaluating other ways of generating docs, and (2) this is just a piece of > the larger meta-environment needed to support a rich component ecosystem. > > Our current thinking around this meta-system goes something like this > (cribbed from some other notes I have): > Goals > > - > > Decentralized (flexibility, decoupling, allow third-party innovation) > - > > Rich materials > - > > Low barrier to entry > - > > Free (support free server options) > - > > Easy to set up > > Leverage > > - > > Provide (optional) out-of-the-box solutions for docs, examples, > sandboxing (moar components!) > - > > Use free GitHub services > > Strawman: Requirements > > To participate in the ecosystem a component should have > > > - > > github repository > - > > landing (aka home or index or information) page > - > > demo page > > Component Identity > > A component can be identified as a URL that points to a metadata file. The > metadata (or the URL itself) identifies the github repository and the > dispensation of the landing and demo pages. > No Cost Setup > > Developer can set up live pages using GitHub servers by cloning the > component repository into a gh-pages branch (and including dependencies; > iow, clone working copy, bower install, push to gh-pages branch). This > set up requires no customization and can be automated. > > Example: three-js component installed to gh-pages: > > > landing page: > > http://polymer.github.io/three-js/components/three-js/ > > > demo page: > > http://polymer.github.io/three-js/components/three-js/demo.html > > (Links and content are variously messed up, these are just > proof-of-concept mocks.) > > > > On Wed, Jan 29, 2014 at 7:51 AM, Addy Osmani <[email protected]<javascript:> > > wrote: > >> Picking up on this thread from last year: >> >> For a developer looking to document the elements they're authoring today, >> do we have an answer we can give them? (I've read through Eric's >> self-documenting proposal and agree, it's a beautiful vision). >> >> After playing around with the prototype, however it looks like we would >> need to either agree on an initial base template / format for the >> documentation element or punt to existing tools like JSDoc (which Eric has >> already mentioned has it's own issues as we're dealing with a multi-headed >> beast). >> >> I'm primarily interested in this for Polymer tooling/boilerplate projects >> where recommending documentation practices from the get-go would be >> super-useful. >> >> >> On Monday, 8 April 2013 20:02:19 UTC+1, Eric Bidelman wrote: >>> >>> Inspired by Mike K's great idea of self documenting custom elements, >>> I've written a proposal to formalize the effort. >>> We have a great opportunity here to come up with best practices early on. >>> >>> *Proposal: Self Documenting Custom Elements <http://goo.gl/X5DxO>* >>> - prototype <http://goo.gl/0pdSW> - a custom element that uses this >>> method. >>> - it's <wc-documentation> <http://goo.gl/qzW7P> (best viewed in >>> Chrome Canary to get ::distributed()). >>> >>> [image: Inline image 1] >>> >>> Things I like about this approach: >>> >>> - The delivery mechanism is <link rel="import">. >>> - Becomes the "view source of custom elements". Click an import's link >>> -> get its docs. >>> - The docs themselves are custom elements >>> - works reasonably well in other modern browsers, especially if the >>> toolkit polyfills are included. >>> >>> Looking for everyone's feedback. >>> >>> Eric Bidelman >>> >> Follow Polymer on Google+: plus.google.com/107187849809354688692 >> --- >> You received this message because you are subscribed to the Google Groups >> "Polymer" group. >> To unsubscribe from this group and stop receiving emails from it, send an >> email to [email protected] <javascript:>. >> To view this discussion on the web visit >> https://groups.google.com/d/msgid/polymer-dev/75b0e259-cd73-4806-b6ee-00cd7b1b7a17%40googlegroups.com >> . >> >> For more options, visit https://groups.google.com/groups/opt_out. >> > > Follow Polymer on Google+: plus.google.com/107187849809354688692 --- You received this message because you are subscribed to the Google Groups "Polymer" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To view this discussion on the web visit https://groups.google.com/d/msgid/polymer-dev/1f28b5fe-9881-42be-9b86-1df6d6018238%40googlegroups.com. For more options, visit https://groups.google.com/groups/opt_out.
