That was quick! Thanks Scott. Maybe once you guys have fleshed out the docs strategy we could figure where this should live long term? :) pp vs wc On 24 Feb 2014 20:02, "Scott Miles" <[email protected]> wrote:
> >> Scott, can <polymer-doc-viewer> be used for non-Polymer elements? > Theoretically...if not practically? :) > > Absolutely, this is always our goal. In my view, we vend 'web components' > technology primarily, and actual elements only secondarily. > > >> What do we think about this: > webcomponents.org/docviewer?element=http://components-r-us.com/my-tag.html > > I made a POC of this idea here: > > http://polymer.github.io/polymer-doc-viewer > > > For example: > > > http://polymer.github.io/polymer-doc-viewer/?//polymer.github.io/google-map/components/google-map/google-map.html&//polymer.github.io/polymer-localstorage/components/polymer-localstorage/polymer-localstorage.htm > > > Scott > > On Mon, Feb 24, 2014 at 10:12 AM, Eric Bidelman <[email protected]> wrote: > >> Scott, can <polymer-doc-viewer> be used for non-Polymer elements? >> Theoretically...if not practically? :) >> >> >> On Mon, Feb 24, 2014 at 10:09 AM, Addy Osmani <[email protected]> wrote: >> >>> I would absolutely <3 that. Being hosted on wc.org also makes it easier >>> for us to encourage those writing elements with Brick/X-Tag/anything else >>> to use the same docs strategy. >>> >>> >>> On Mon, Feb 24, 2014 at 6:05 PM, Eric Bidelman <[email protected]> wrote: >>> >>>> 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-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. >>>>>> >>>>> >>>>> 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/CAAKPnK_9zNBan_vN9-96BrA7%2B1oHeEb6Ux8A7cSWBNe9Hq9-DA%40mail.gmail.com. For more options, visit https://groups.google.com/groups/opt_out.
