On Nov 28, 2007 11:37 AM, Ches Martin <[EMAIL PROTECTED]> wrote:
http://wiki.pylonshq.com/display/pylonscookbook/Suggested+Improvements+to+the+Documentation
This looks really complete, thanks. It will be quite helpful as a
documentation checklist.
The Pylons book has some preliminary chapter drafts that address many
of these questions. Unfortunately it's in a reorganization / mad
draft-writing phase so they aren't ready to be posted yet. But I can
say that they cover:
- Complete Mako usage, and examples for configuring several other
template engines (but not their syntax).
- QuickWiki I: a simple SQLAlchemy/ORM application. QuickWiki III:
advanced Pylons features. A blog tutorial has not been mentioned but
may be a natural extension of that.
- Testing: James agrees this is the biggest hole in the Pylons docs,
and is making it the top priority for his next draft. I need this so I
can write tests for the examples in the book. :)
- ORM/DB: my Overview page is meant to be the seed for this.
SQLAlchemy will be part of the official docs, and I hope there will be
comprehensive links to add-ons/alternatives.
There has been ongoing discussion re which scheme to recommend by
default. The top contenders are SQLAlchmey/ORM, SQLAlchemy/SQL, and
Elixir. My opinion is QuickWiki I should demonstrate basic
SQLAlchemy/ORM reading and writing, and QuickWiki II "something more
advanced". Ben has recently suggested Elixir, once it grows a feature
to dump its configuration to standard SQLAlchemy statements. I'm
afraid that Elixir, while it may be useful to those who understand
what it's doing behind the scenes and just want the convenience, may
be too limited and magic to be a good default. I'm also suggesting
SQLSoup get more mention.
- 0.9.7: Routes enhancements, optional @expose with *some* TurboGears'
functionality (not dispatching), new middlewares required in
middleware.py, what else?
@expose will bring the issue of 'c' vs non-'c' for template
variables to a head, because the exposed action will likely return a
dict that's passed to the template. I'm not sure how this will be
resolved, given that it might force people to change ${c.foo} to
${foo} and vice-versa in their templates when switching to/from
@expose.
- Concepts of Pylons: hasn't been addressed but would make good
introductory material.
- Forms: added a link to the Forms overview page, which links to all
the alternatives. The book has a forms chapter covering
FormEncode/htmlfill/webhelpers, and later an Javascript/AJAX chapter.
James mentioned FormEncode was hard to document: the docs are very
minimal, and he found several bugs that make it impossible to use
FormEncode as it was apparently intended. This chapter will take lots
of organizing so don't expect it soon.
- Virtual environment: I added this section and the following:
"virtualenv, zc.buildout, and the older workingenv/virtual-python.
Because Pylons has many dependencies, users need a way to try it out
without putting it in site-packages, and to keep libraries for
different applications isolated. Virtualenv offers the most familiar
environment for developers (use easy_install as normal). zc.buildout
has cached eggs, a configuration file, can update all eggs in one
step, and has a documented way to install it without setutoops in
site-packages. Perhaps all these features can be ported to
virtualenv."
- Paster shell, Paginator, profiling, memory usage, Planet Pylons: no comment.
- Building a site, programmatically configuring: something needs to be
done to improve the docs here, but I'm not sure what.
One meta-issue is that the Pylons Cookbook space has become the
dumping ground for everything because it's the only space everybody
has guaranteed write access. There are topics such as this, improving
the Pylons core, etc, that aren't really Cookbook material.
Likewise, the Pylons Community space has tutorials which arguably
*are* Cookbook material. It has never been made clear what the Pylons
Community space is for. Is it for marketing/branding/website topics?
Is it a miscellaneous space for community members to put anything in?
--
Mike Orr <[EMAIL PROTECTED]>
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"pylons-discuss" group.
To post to this group, send email to pylons-discuss@googlegroups.com
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
-~----------~----~----~----~------~----~------~--~---
