Hello Scott, Just picking up on this thread once again :) We are currently evaluating how to prescribe best practices around component documentation as part of WebComponents.org and a Polymer boilerplate project.
The current setup you have based on <polymer-doc-viewer> and <polymer-home-page> so far work quite well, however I noticed that the source appears to rely on a self-hosted endpoint: http://turbogadgetry.com/bowertopia/components/ If we were to model a way to auto-render docs using your setup today, would calling the above endpoint be feasible or would you prefer for us to (1) wait until a more concrete docs approach has been fleshed out or (2) a way to host this elsewhere (AppEngine?) so others can use it without causing issues. Cheers! On Wed, Jan 29, 2014 at 6:03 PM, Addy Osmani <[email protected]> wrote: > 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]> 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/CAAKPnK8ce1bDtSZG0W0RWiQMiz5CfkdWuzmRKuwtzdNNsZE03Q%40mail.gmail.com. For more options, visit https://groups.google.com/groups/opt_out.
