Many thanks for going to the trouble to write all this. I should say that I'm impressed by those parts of TurboGears that I understand. It can be forgiven that I'm frustrated by things that I don't, I hope. :-)
On Jul 14, 2010, at 21:08 , Michael Pedersen wrote: > Note that I did not say that Routes worked. I did not say to use Pylons > documentation to work on a TurboGears project. I said that Routes Integration > worked. See the following for information about how to integrate Routes with > your application: > http://www.turbogears.org/2.1/docs/main/RoutesIntegration.html Certainly not, but on the other hand, you and no-one else has said not to. It doesn't take much reading about TurboGears to learn that the project is about integrating other projects. I started out trying to follow the TG docs, and when I ran into trouble trying to make things work with those, I figured — and it indeed appears to be the case — that there would be more details about the individual parts that are integrated in TG, in the documentation for those separate projects. I submit that this is a pretty reasonable way for me to have reasoned. If there are caveats that should have applied to this line, I didn't see them, and it would be useful to add them, prominently, in the introductory material. > On Wed, Jul 14, 2010 at 6:46 PM, Guyren G Howe <[email protected]> wrote: > I'll note here that "The TurboGears Way" doesn't make it clear that Pylons > isn't just part of TurboGears, but is modified, and that you shouldn't just > do things like TurboGears does it. In fact, I think it suggests the opposite. > > Thanks to that title, I managed to figure out the page you were looking at. > For anybody else following along, the page is here: > http://www.turbogears.org/2.1/docs/main/TG2Philosophy.html > > Pylons is, indeed, at the core of the system. However, that does not mean > that whatever works in Pylons works in TurboGears trivially. Routes are just > one example, I'm sure there are others. That's a big part of why we have 531 > files in our docs repository as of right now. If TG were nothing more than > Pylons, well, we wouldn't have much need of those documentation files, would > we? Pylons looks like a great project, and so does TurboGears. This is all fine. But where in the TG docs does it say something like the paragraph above? Understand: I say this with respect and admiration for what you're doing. I'm just hoping that my frustrations can lead to some improvements in the documentation. > One thing that puzzles me slightly is that the page you are looking at is > towards the bottom of the documentation stack. It comes in the next to last > of the main segments, and it's linked about halfway down that page. In other > words, finding it is not terribly easy, especially in comparison to finding > the tutorials we have written (which can be found here: > http://www.turbogears.org/2.1/docs/tutorials.html ). Those tutorials show you > how to use the TurboGears Object Dispatch method in great detail. And yet, > from the way you are speaking, you have not read the tutorials and are > instead attempting to dictate the way you feel TurboGears should be based on > something you feel you read in one of our documentation pages (but is not, in > any way I can find, actually there). I found that page because the "why" or the "philosophy" of a project are in my mind important. I saw that in some TOC or something somewhere, and read it closely. It still seems a reasonable takeaway from that and other statements I read about how TurboGears is put together to assume that the docs for those other projects are relevant to TG. > Please, forget that page you're talking about exists. Go, read the tutorials. > There's a lot in there, and it will explain a great deal to you. I looked at the tutorials. I looked at the documentation. The tutorials I don't think cover restful routes. I think I absorbed what was in the tutorials and the documentation just fine. I put this: map.resource('incident', 'incidents') as the first route entry in my routes file, and it didn't work. The tutorials don't cover why that doesn't work; the docs don't cover why that doesn't work. All the material says that it should work. What was I to do when it didn't? I spent a good deal of time tracing through the framework and trying different things. After a while, I started posting here. I believe I understand the tutorial material just fine, but I'm trying to go beyond the basics, by fixing something that's not working for me. > I have until now been under the impression that TurboGears is a project to > integrate Pylons with Repoze and so on, so they are easy to install, and so > there are tools available that can run across them. I believe it is important > to make clear that TurboGears is not just a superset of Pylons. > > What statement could be put into that page that is not already there? This is > your chance: I'm the guy who does the most work on the documentation itself > right now (with the possible exception of Mike Fletcher, that guy is a real > boon to the team). Tell me what should be there. Well, given what you've said here, if I understand you correctly, everywhere there is mention of how TurboGears integrates other projects, you should have something like this: <p><em>Nevertheless</em>, although TurboGears incorporates libraries such as Pylons, the most effective way to use TurboGears isn't necessarily the one you'll read in the documentation for those projects. Some of the most prominent examples include:</p> <ul> <li>Restful APIs are best handled with tg.controllers.RestController, rather than doing paster restful restcontroller thing things. <a href="…">Here</a> is a discussion of why</a> <li>Although we integrate the Routes project, you should mostly be able to use Object Dispatch. <a href="…">Here</a> is a discussion of why we don't particularly favor Rails-style routes files<and I'd still like to know why that is> … In general, <insert general discussion of why the TG project leads to what is idiosyncratic code in the individual components is no longer idiosyncratic code in the integrated project>. > On Wed, Jul 14, 2010 at 6:49 PM, Guyren G Howe <[email protected]> wrote: > In fact, I'll also suggest that if paster restcontroller is deprecated, it > should be removed or at least issue a warning when one tries to use it. If it > is not deprecated, then the comment should be removed from the top of the > generated file and replaced with whatever instructions are appropriate to > getting the generated controller to be picked up by the routing > infrastructure. > > Who said that "paster restcontroller" is deprecated? That particular piece > comes from Pylons. In fact, if you do "paster help", you will see it listed > under pylons, not TurboGears2). Short of us telling the Pylons team "Hey, > your restcontroller in paster hurts, take it out", what would you have us do? > Especially since, for people doing pure Pylons, that is a helpful command to > have? We have no more control over Pylons than you do. We can't remove their > template for them, and we can't update it for them. Two totally separate > projects. > > Now that I've answered those specific points, time to get back to the > original issue: Object Dispatch takes the place of Routes in a TurboGears > project. This results in your having setting up your URLs extremely easily. > Let's assume you have a simple contacts segment of your web application. > Assume you already have your model set up like so: > > class Contact(DeclarativeBase): > id = Column(Integer, primary_key=True) > name = Column(Unicode(255)) > emailaddress = Column(Unicode(255)) > phone = Column(Unicode(64)) > website = Column(Unicode(255)) > > Now, assume you want to create a Rest Controller that supports CRUD. Turns > out that this is *really* easy with the tools that are available. First, make > sure that tgext.crud and sprox are installed: easy_install tgext.crud sprox > > Next, create a new controller with this as the class: > > from project.model import Contact > from tgext.crud import CrudRestController > from sprox.tablebase import TableBase > from sprox.fillerbase import TableFiller, EditFormFiller > from sprox.formbase import AddRecordForm, EditableForm > > class ContactController(CrudRestController): > model = Contact > title = 'Contact Management' > > class new_form_type(AddRecordForm): > __model__ = System > > class edit_form_type(EditableForm): > __model__ = System > > class edit_filler_type(EditFormFiller): > __model__ = System > > class table_type(TableBase): > __model__ = System > > class table_filler_type(TableFiller): > __model__ = System > > There, the CrudRest form is now done. You can do lots more with it (check out > Sprox at http://www.sprox.org/ and tgext.crud at > http://www.turbogears.org/2.1/docs/main/Extensions/Crud/index.html for more > information), but that's the main part right there. So, now, how to get this > visible in your application itself? Open up project/controllers/root.py and > add this line to your RootController class (after adding the import to import > ContactController): > > contacts = ContactController(DBSession) > > You're done. You now have full CRUD on your RestController. > > Suppose you would like to be able to move URLs around without having to > manually maintain some sort of navigation bar in some separate file? Check > out http://bitbucket.org/pedersen/tgext.menu for something that will manage > your navigation bar. Need to be able to provide XMLRPC in your application? > Check out http://bitbucket.org/pedersen/tgext.xmlrpc for an XmlRpcController. > > My overall point is that, right now, it seems like you are railing against > what you believe TurboGears should be, instead of looking at what it is. Try > looking at what it is, and seeing what it can do. You might be pleasantly > surprised. Sorry if I gave the impression of Railing, I was just discussing things from the perspective of what I know, which is Rails. There are things here (routes) that appear to let me do what I am used to, only *they didn't work for me, and still don't*, even though they appear to be very simple and basic. I am okay with leaving that issue aside since apparently I'm not doing things the idiosyncratic way, but if it's not idiosyncratic TG to implement a restful api using routes, the docs on routes should say so, is all I'm saying about that. And I'm still wondering why that level of abstraction — separating the routes from the api calls they map to by default — isn't seen as either necessary or at least desirable. Is it because if I decide to rewrite my controllers without changing my routes, I can add routing later, and using Object Dispatch is simpler until then? That's the only answer I can imagine, and I think it deserves a comment somewhere in the docs. A lot of people are going to come from Rails or one of the now many Rails-inspired frameworks, and go looking immediately for how to set up routes. A "TG for Rails developers" would be exceedingly useful in this kind of regard. I'll happily write one once I'm more familiar with TG. In fact, I've done more than my fair share of technical writing in my time, and I'll happily contribute to the docs, if you can help me get to the point where I understand things. :-) > Oh, one last thing: All of the code in this email is completely untested. I > don't even know that I got indentation correct. I know it should work, but am > not positive that it does work. Sure. Again, I greatly appreciate you taking the time to write all this. I hope this interchange can be genuinely helpful in improving the docs. Believe me, I understand how much work it takes to produce documentation. My impression is only that you don't have the resources to be as thorough as I would love (I'm sure you would love, too — we all want everything now, right?). I should say finally that the docs for TG that are there are of a very high standard. There can always be more docs and more refinements, right? :-) -- You received this message because you are subscribed to the Google Groups "TurboGears" 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/turbogears?hl=en.
