>> 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/CAHbmOLbXn7CCecCYxrKv0Ug3v6oCKococTQn7mJHdg7fW%3D4RDw%40mail.gmail.com. For more options, visit https://groups.google.com/groups/opt_out.
