On Mon, Sep 13, 2010 at 10:45 AM, Ben Bangert <b...@groovie.org> wrote:
>> 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.
Can it be made into a request method so you don't have to pass the
request object? That would be more OO.
>> 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.
How would you do this then? If I have all the source repositories in a
subdirectory and exclude them from auto-building, can I still link to
subproject .rst files and it'll include all their dependencies? Does
".. autoclass" work through subprojects?
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.
> 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.
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.
> 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'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.
> 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.
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.
> 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.
I don't think I've encountered legacy_view yet. How does it work?
BTW, where is the cache?
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.
> 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.
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.
> 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.
Do you mean just changing the message to "ImportError: please install
the 'formencode' package", or something more elaborate?
--
Mike Orr <sluggos...@gmail.com>
--
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.
