On Sep 13, 2010, at 12:09 AM, Mike Orr wrote: > I'll move some of the background paragraphs into separate pages. But > this page will focus on the minimal app. > > Do you have any sample applications in both Pylons 1 and Pylons 2 that > I can include? The more sophistocated one with multiple actions and a > redirect may be a start.
Not at the moment. > Where is pylons.url now? request.url? from pylons.url import route_url Then just, route_url(request, 'route_name', **extra_args). It works largely like the BFG route_url, except honors an additional URL generator option that a route can have. This is how I have a sub-domain setup implemented. I'll prolly have to move route_url elsewhere, as there's a 'url' object hanging out in pylons/__init__.py. > That may be too much to manage this phase. But I can link to the manuals. > > I guess I can make a Makefile that checks out the repositories of all > the dependencies, and let Sphinx recursively build all the manuals. It > started doing that with BFG and Pylons unexpectedly until I excluded > their parent directory in conf.py. Ah, unfortunately that won't be good enough. Chris and I had chatted about trying to do something with Makefiles so that things would be included, but unfortunately this means that the included stuff retains reference to its own docs. This creates a very hacked up reading experience that is not going to be pleasant. > I think we need the distinction for the transitional phase. Existing > Pylons users need to understand where everything is. So they can find > the docstrings in the source code, for one thing. And I, as a reader, > would certainly want to know where the different Request methods come > from. Otherwise it's too confusing, especially if I'm trying to figure > out how Request changed. Well, I guess I just mean that I wouldn't waste the reader's time explaining the history of every object they might want to use, vs just saying, here is where you import the Request from, and then linking to its API docs. Our API docs can mention where it comes from, which methods come from where, etc. There's no reason to bog down the documentation explaining things that the reference API can explain as it documents the objects. This also means that as we document *everything* we expect Pylons users to have, we can include doc strings with Sphinx as needed, and editorialize them ourself as well. Sphinx makes it quite easy to ignore doc strings, or ignore module docs and supply your own. That'd be a good place to add in additional info about what comes from where, etc. If the docs are written with the expectation of a first-time Pylons user, then an existing Pylons user should be helped just as much to see where things are. I don't think de-emphasizing all the packages involved means that someone wouldn't know where something they need to use it. It just means we wouldn't waste the users time explaining the history of XX, or why ZZ was done. Keep the focus on how to do it, where the objects they need to import are, and point them to the reference API for said objects. I plan on adding a "Design Defense" page similar to what repoze.bfg has, that explains the 'why' of the design decisions in Pylons, so we can avoid repeating explanations throughout the docs, which should keep a tight focus on what the developer needs to know to get going. Then have a section for migrating users that explains what moved where, how to use new features with an existing app using the legacy_view, etc. For example, take sessions, Pylons 2 has an add_sessions that sets them up, and a request.session object they make use of for the session. I would imagine the Sessions section would indicate that you use add_sessions, how to use the request.session object, how to change the configuration options, and then send the user to the Session API docs. The Session API docs would include the complete set of configuration options, include any relevant info on the package (Beaker) that actually implements the sessions, and then have all the relevant module docs someone wanting all the details would need. This keeps the "How to use Sessions" bit short, concise, and fast for a developer to get going with, and then leaving the Reference API section to fully document the additional configuration options, what objects come from where, what type they are, etc. The existing Pylons user will generally jump straight to the Reference section when they need to know about an object, or its methods, or configuring it since they already know *how to use* it. Alternatively, a documentation style that might be worth trying, is what Mike Bayer has done with the latest version of the SQLAlchemy docs, which I'm kind of liking. That is, we'd have a "Pylons Overview" chapter, that includes a short bit on how to do "all the standard things" a Pylons user would want to do. Installation, Hello World, Using Sessions, etc. Each one then links to the full chapter, and the full chapter goes into all the details, and includes the API docs in-line. Sphinx makes either style pretty easy, so its kind of tempting to try out the approach Mike Bayer is doing. > Decorator is really a basic Python utility that belongs in the stdlib. > It would be silly to drop it now if we might need it again later. The only purpose of decorator is to ensure the function retains the same signature. Having code inspecting things for signatures is rather annoying to begin with, and has frustrated a lot of Pylons users writing decorators. I should hope we won't need it later. :) > You talked about a separate Pylons-FormEncode package. Although I > don't know what it would include besides the dependency. Buit > WebHelpers could go with that. I think it would include helpers that can make the assumption that you're using Formencode and Pylons. @validate is an example of something that would go in there, or since @validate is so problematic, some other Pylons appropriate utility functions. > What try/excepts? I don't think there's anything in the Pylons core or > application template that imports FormEncode or WebHelpers. Routes is > more central, of course. What's wrong with a Pylons1-Compatibility > package like I suggested earlier. Just tell people they need to > install that if they want to run a Pylons 1 applicaton under Pylons 2. > It's similar to Pylons 0.10, which keeps compatibility code, but done > in a different way. I think there are some imports in Pylons of FormEncode and WebHelpers actually. The secure form stuff from Pylons decorators makes a WebHelpers import, as it also makes a FormEncode import. We can't make a separate pylons-legacy package, because then all the stuff they're expecting to import from Pylons.... wouldn't be there. And I want Pylons 2 not to cause someone to have to change their project unless they're using new things. > But if the try/excepts have to be in the application, we're kind of > screwed, because we can't go auto-modifying people's applications and > breaking them. No, I meant in the places where Pylons is importing WebHelpers and FormEncode, it wraps the imports in try/excepts so that the legacy decorators will only work if the user has installed FE/WebHelpers, vs having it as a Pylons requirement. - Ben -- You received this message because you are subscribed to the Google Groups "pylons-devel" group. To post to this group, send email to pylons-de...@googlegroups.com. To unsubscribe from this group, send email to pylons-devel+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/pylons-devel?hl=en.
