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/CACGqRCCe%2Bn%2BTEHQe52L9MJua8drRewyApwvdCRxhbMmho%2B%3D-%3Dg%40mail.gmail.com. For more options, visit https://groups.google.com/groups/opt_out.
