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]> 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]. > 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/CAHbmOLYHHr-FmDv1-zGoJ7CBy36QLu365cPb5PQH9-HyMdy3bw%40mail.gmail.com. For more options, visit https://groups.google.com/groups/opt_out.
