On Wed, 2012-02-08 at 09:44 -0800, Iain Duncan wrote: > > > On Mon, Feb 6, 2012 at 12:02 PM, Mike Orr <[email protected]> > wrote: > +1 for splitting the manual into simple and advanced, however > that's > defined. Simple = normal application usage based on the > built-in > scaffolds. This would include both Chameleon and Mako, and > maybe > traversal. Advanced = optional customizations such as new > renderers or > ZCA. > > > > On the topic of parallel docs, here's what I would do, adopt or reject > as you see fit: > > > - The easy book/docs focusses on Pyramid in 'Pylons/Django' style, > which is how most people are going to want to be introduced. It > doesn't dwell on interfaces, adapters, zcml, views as classes, > overriding resources through zcml, etc. Readers of the easy book just > get up and running with Pyramid as fast as possible. The acid test of > this stream is "how good and quick was your hit the ground running > experience?" This book impresses all those people who like to write > "web framework shootouts" after only using the framework for a day > ( barf! ) > > > - The advanced book goes Under The Hood. It explains what's happening > and how it all is lashed together as a component architecture system, > and all the myraid places you can hook into or override this system. > It covers views as adapters, registering them by interfaces, > zcml_pyramid, using the resource system, more on custom factories, > writing your traverser, etc. The acid test on this stream is "could > you replace any component in the pyramid system with a version of your > own after reading all this" > > > I would personally make them connected. So each page in the easy book > has a link to "under the hood", where we find out how pyramid actually > accomplishes this and where you could tinker with how it's done. And > the advanced section heavily points at good further reading. ie, it > doesn't have to be the definitive guide to using the ZCA, there > already is a good one, so it being advanced, it can be fairly terse on > what you use a zca interface for and point somewhere else for more > details.
Pyramid's use of a ZCA registry is still an internal implementation detail, and as such isn't really intentionally exposed to the outside world. It won't make much sense for the docs to explain how Pyramid works in terms of ZCA vocabulary such as "adaptation", or even link heavily to things that explain what adaptation, etc is. Instead, explanations of framework hooks and such should just tell them which Configurator methods to call, just as the docs do now. Theoretically, Pyramid may disuse the ZCA in a future major release (although it's highly unlikely). ZCML is purely an add-on package via pyramid_zcml, with its own docs. The core Pyramid docs will not cover it, although they might mention it in passing. - C -- You received this message because you are subscribed to the Google Groups "pylons-discuss" group. To post to this group, send email to [email protected]. To unsubscribe from this group, send email to [email protected]. For more options, visit this group at http://groups.google.com/group/pylons-discuss?hl=en.
