On Sep 13, 2010, at 11:49 AM, Mike Orr wrote:
> Can it be made into a request method so you don't have to pass the
> request object? That would be more OO.
Sure, request.url though makes it ambiguous if its the request URL vs a url
function. Ian called it request.link in his example app using Routes, so maybe
something like that?
> Or do you have to paste the markup text from the subprojects and
> convert all "autoclass" to "class" by hand? The problem with this is
> it would gradually drift out of date unless you went through every few
> months looking for differences between your docs and the originals,
> which would take a lot of time.
Yes, you paste in the ones where appropriate (some of the sub-projects have
none, or little docs, so we'd have to write those). This is part of the main
issue btw, when we punt on doing it and just tell people to "go look at that",
and then the docs we pointed them to are incomplete, fail to mention how it
applies in the context of the framework, etc. we just.... fail. Yes, it takes
time to document the big picture and its parts effectively, in some cases we
can copy/paste or still have Sphinx auto-generate an objects doc from the
doc-string still, but in other cases we'll have to fill in gaps.
Regardless of how its done, using and documenting Pylons as it consists of
other projects requires time to keep the docs up to date as dependencies
change. We're not doing anyone a favor by not addressing this issue at the
moment. I don't think this means we need to document *all* of every single
project, but we need to copy the docs or document anything ourself which we
expect a Pylons developer to use that comes with Pylons.
Except for BFG, the other dependencies are pretty much 'done' though, their
docs aren't changing as they're not really changing anymore.
> Easy for you maybe. I still have to pour through the Sphinx manual
> sometimes wishing it would explain more clearly how to do something.
> If we could sprint together it would be easier.
Agreed.
> I'm inclined to agree with James, that explaining it at a non-Python
> or non-web-developer level triples the workload. (Once to write the
> new text, and again to test all the examples on platforms you don't
> use.) Anyway, once we get the higher-level text squared away, the
> newbie text will be just a matter of filling in the background. And
> James' book provides a guide on what the newbie needs explained.
Oh, I'd never aim it at a total non-Python or non-webdev. That's what books are
for. Pylons documentation is for:
1) How do I do XXX with Pylons?
2) What are all the options to do XXX with Pylons?
3) How do I extend and utilize other web dev patterns with Pylons?
These leads to a set of docs that are generally fairly short and concise to go
over how to do various things (prolly a Quick Start / Overview), where each
section hyperlinks them to the more extensive web dev patterns of that topic,
all of which link to the reference docs (which show all the options).
Once you know how add_sessions works, there's really no point in wasting space
in the narrative docs explaining each option, when just a list of all the
options and what they do would work just as well. The latter being the
reference API docs.
> OK, maybe I can outsource that part to you. The first page ("Intro")
> starts to get into that (at least re the changes since Pylons 1), but
> it just takes so long to write with all the necessary background that
> I postponed it. Plus, you guys can remember the new practical
> features better than I can.
Sure, sounds good.
> I don't think I've encountered legacy_view yet. How does it work?
There's a legacy pylons template that shows it. It essentially lets you hook up
an existing Pylons app with zero changes, and then start adding new handlers
with the Configurator.
> BTW, where is the cache?
No where right now. Technically all you need to do is import the cache module
from Beaker, set the options, and use @cache_region as desired. I should prolly
add a setup function for that on the configurator and an import in Pylons
though, as that'll make it feel more cohesive.
> Will there be an app_globals? I'd also suggest a thread_locals (or
> app_globals.locals), because uses keep wondering where to put
> threadlocals and end up reinventing it themselves.
Technically, those can be added to the application registry as 'utilities', but
it'd make sense maybe to have a config arg that lets you designate some
functions that want to setup 'global' type objects, and when configuration is
completely done, it'd call those functions and let them set it up. That'd also
ensure that they're only setting up the 'app globals' when all the config
information is available.
> I was disconcerted when I looked at the SQLAlchemy docs last week and
> the entire API section seemed to be missing. I actually thought it was
> a bug and figured it would come back in a few days. Then I noticed
> that the API docs were integrated with the narrative sections rather
> than all together. I'm not sure if I like it or not. Do all the API
> sections have narrative sections? Because sometimes I need to look up
> an undocumented method, e.g., to access column metadata in a program.
Yea, its a tough one. Let's stick with having a separate Reference API section
for now. I should note I have no plan on having it organized how Sphinx does
'modules' right now. I think it kind of sucks how Sphinx just makes an
alphabetical listing of all the modules. Instead, I'm going to organize the API
section the same as the narrative... by topic. So there'd be a 'Sessions'
section in the API docs, and that lists all the functions/classes/modules you
should need to know about for everything that is 'session' related. I get the
distinct impression this would help people find the right
module/class/function, since right now ppl end up asking these questions on the
Pylons channel and other ppl have to find it and link them to it.
> Do you mean just changing the message to "ImportError: please install
> the 'formencode' package", or something more elaborate?
Just that, so that if they had old code that wanted to use it, they should
install it.
Cheers,
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.
