Being able to view live docs without having to install anything would be *very* nice.
What do we think about this: webcomponents.org/docviewer?element=http://components-r-us.com/my-tag.html /docviewer would contain <polymer-doc-viewer> and render the docs for my-tag.html (or whatever URL you pass it). Anyone that follows the documentation practices (CORs enable their imports, uses YUIDoc comments, etc) can use this. Thoughts? On Mon, Feb 24, 2014 at 9:36 AM, Scott Miles <[email protected]> wrote: > Hi Addy, > > My plan is for the core team is focus this week on tightening up our > component set and fleshing out the docs and on-ramp materials. You're just > a bit ahead of us. I hope to have clearer answers in a few days. > > I'm leaning towards modifying our standard `index.html` to simply suggest > you install `polymer-home-page` instead of redirecting you to an external > site. WDYT? > > Scott > > > On Mon, Feb 24, 2014 at 3:34 AM, Addy Osmani <[email protected]> wrote: > >> 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-pagesbranch). 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. >> > > 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/CAHbmOLbND3RpoYW1wbH6d6UoqcVA_am1YP%2BDVS6q%3DRWD6bQaag%40mail.gmail.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/CACGqRCCFX2Ti_1o1EPADLTayZaA89n7KtVh%2BmtAR1UfvTOkoWw%40mail.gmail.com. For more options, visit https://groups.google.com/groups/opt_out.
