Use this page to point out any docs you find on the wiki that are incorrect, out of date, or inadequate in some way. Please add a link to the page in question, along with a brief comment. There is also a "wish list" section below, where you can leave suggestions for tutorials or aspects of Pylons that you'd like to see covered or expounded upon in the future. Together, these will provide a useful resource for assessing or prioritizing tasks for doc sprints or volunteers.
Please act respectfully, and direct discussion to the IRC channel or the mailing list , rather than posting running commentary on this page.
Of related interest is the Shared Project Development space, where you'll find proposals for archetypal applications deemed valuable to the community.
Documentation goals
Mateusz Haligowski wrote a good summary of the kinds of documentation Pylons needs:
- very general tutorial (like the one on the PylonsHQ)
- expanded tutorials - general tutorial divided into parts, with deeper explanation of what happens
- HOWTOs on most popular tasks - something I'm really missing on Pylons. I still can't do a good user system at my application
- Up-to-version screencasts - they are lovely indeed, provided that they consider the current version.
Pylons/TurboGears sprint March 2008
These areas were noted in the sprint as requiring documentation. (Some of these are TurboGears specific.)
| Topic |
Documentation needed |
| TurboGears 2 |
- Decorators
- Dispatch
- What's new in TG2?
- Migrating to TG2?
|
| Pylons |
- Controller subclasses
- Middleware configuration
- Transaction log (paste.translogger)
- Localization
|
| SQLAlchemy |
- ORM tutorial
- Expression language
- How to do transactions
|
| Genshi |
|
| FormEncode |
- Basic overview
- TG2 tutorial
- Chaining validators
- FancyValidator vs Schema vs Form
- Compound widgets
- How to make validators in DBSprockets and ToscaWidget
- Re-use
- Validating checkboxes and dates
|
| Mako |
- Setting engine options
- Using the new render() function and customizing it
|
| Beaker |
- Sessions
- back-ends: memcached, database, filesystem, when to use which
- Secure cookies
- Caching (yes, Virginia, you can make your own caches in Beaker, even in Pylons)
|
| RuleDisplatch |
- (Will be eliminated in ToscaWidgets, so no need to document)
|
| WebHelpers |
- Needs a coherent manual after WebHelpers 2 is stablized
|
| WebOb |
- Basic usage
- Middleware example (reimplement paste.translogger, explain StatusCodeRedirect
|
| WebTest |
- Integrating it in the frameworks
|
| ToscaWidgets |
- Needs its own sprint to document.
|
| Nose |
|
| Paster |
- Document the special Pylons/TG commands.
- Mention that "paster --help" shows different commands depending on if you're inside a project directory.
|
| WebError |
|
| Toolbox2 |
|
| Tutorials |
- Testing your application (Pylons) (TG?)
- Deployment
- Wiki (QuickWiki basic tutorial)
- Contact manager (advanced tutorial)
- Mako
- Getting started
- Making a combined Pylons/TurboGears application (with both kinds of controllers, and a generic WSGI controller)
|
| Babel |
- Integration
- Extraction
- Localization
|
| DBSprockets |
| DBMechaic |
| Authentication/Authorization |
- Needs Pylons documentation
|
Corrections and Improvements
| Page or Topic |
Comments |
| Mako |
As the official template language, there should probably be a Mako doc in the Official section. Most importantly, where does Pylons depart from Mako defaults, and what options are set?
|
| Blog Tutorial |
This wasn't very feature-complete to begin with, but it's probably enough to make it worth getting up-to-date and extending. It's also linked on the PylonsHQ front page, while QuickWiki is not... User  gardsted began updating – linked in the comments. |
| Testing stuff |
Merge existing testing docs into one Official Doc section. Ideally I think model and functional tests should be added to QuickWiki and these testing docs should be rewritten as a follow-up to the QuickWiki tutorial. Also see the paster shell bit in the Wish List below.
- Emphasize that the basic setup for model testing should be similar regardless of the persistence layer you're working with
- Take disambiguation into consideration. Rails has proliferated the notion that 'unit tests' refer specifically to your model rather than simply small, isolated test cases, and there are varying definitions of 'fixtures' too. Just make sure that Pylons' docs use consistent terminology, whatever it is.
- Customization with nose plugins.
- writing tests for form validation, auth
|
| Adding Documentation to Your Application |
This doc would probably be accurate, except that the setup.py pudge command doesn't work right now. Probably the larger issue is determining the state/fate of Pudge. References #319 and #302 |
| Babel localization |
Babel l10n date, currency functions. Currently only gettext is really covered there. References #183 |
| pylons.config |
The Cookbook article Getting Data from the Configuration File hasn't been updated for the pylons.config consolidation. Is this a candidate for going in Official Docs somewhere anyhow?
- Err, check that – it is already. Remove the Cookbook article if there's nothing left to add to the official doc.
|
| Concepts of Pylons |
IRC user mentioned in passing that this should be updated. Myghty bits should be updated for Mako. What else? |
| Beaker Caching |
Beaker documentation is slim, and the Configuration Options page seems out of date. memcached stuff in particular – the official Mako docs list 'extra arguments for memcached' as TODO, and I can't find specific info for such arguments in Pylons/Beaker docs either.
- Implementing something like Rails' sweepers?
|
| Pylons Community |
There has been some limited discussion about how to better organize and define this space.
- As a small point, we need a note about leaving your name and email addy with patches. It's tough to use code when people attach patches to Trac tickets when logged in as 'guest'...
|
Forms
| Topic |
Comment |
| Forms |
the FormEncode docs are scattered and incomplete. Make a thorough users' guide for Pylons with examples of checkboxes, integer select lists, interrelated fields, custom validators, etc. Also mention the higher-level libraries: ToscaWidgets, FormAlchemy, Django's newforms.
|
| FormEncode |
Building forms for use with htmlfill. You can use a template to build forms, and then fill with htmlfill. I don't think this occurs to lots of people. Also, how to use this with variabledecode to handle nested forms. |
| ToscaWidgets |
Alberto has put out a call for help in extending his ToscaWidgets tutorial. |
Wish List
| Topic |
Comment |
| Virtual environment |
The Pylons docs will recommend Virtualenv, mentioning zc.buildout and the older workingenv/virtual-python as alternatives. Because Pylons has many dependencies, experimenting with Pylons inside a virtual environment is highly recommended, and it can also be useful for deployment. Virtualenv needs a good Pylons tutorial: its own documentation focuses too much on making a bootstrap rather than on how to use it (hint: use the 'activate' command most of the time). We also want to port some features from zc.buildout to Virtualenv: especially an egg cache, and perhaps also a configuration file for replicating an environment.
|
| paster shell |
I agree with  Paul Snively who posted the FAQ entry – paster shell rocks and should be more prominently advertised to new users. So, expand on the FAQ entry and make it a full doc. Discuss how it works (how Pylons loads your app, etc.) and tips for using it interactively. Demonstrate that a paste.fixture-wrapped app is automatically available for emulating requests, etc. as in the testing docs.
|
| Profiling with Paste |
Just a short tip or FAQ entry. Related performance tidbits: setting cache_max_age for StaticURLParser in middleware.py; gzipping, though normally this be handled the level of a front-end proxy server.
- The first part is mostly done in a FAQ entry I started [here]. Just need to figure out where output gets intercepted in Pylons and work around it.
|
| Memory usage |
Some discussion of how to debug memory problems. This post has a bunch of useful information. |
| Planet Pylons |
A small app to aggregate user-submitted RSS feeds, say from the 'Pylons' tag on your blog. Potentially a nice step forward from the blog listing on the Community page, this could also be a user-hosted project. This should be formalized in Shared Project Development. |
| Building a site |
There's a bunch of tasks involved in putting together a complete site, which is separate from a single application. Integrating something like a Pylons app with Trac or wphp would be an interesting example. |
| Programmatically configuring |
I don't think it entirely occurs to people that the Paste Deploy configuration maps to simple Python calls, and you can usefully call those same thing from sources other than configuration. Like, say, a configurator. Or something based on a virtualhost (e.g., use the hostname to set the database parameter, making your app farmable). |
| contrib repo for PasteScript templates |
Not exactly a doc issue, but close. There are myriad useful things that can be done with these. I'd imagine many people will write them for the ORM, auth, unit testing framework or what-have-you that they or their company use, and they'd likely be useful to others. Tesla featured a paster model myfile.py command to generate a model and test stub.
|
| Egg Basics: Paste, setuptools and version control |
Quick overview of what an egg consists of and what Pylons/Paste do with that mysterious .egg-info. Link to reference documentation where appropriate. Some have expressed that touching on this in the QuickWiki tutorial adds density that doesn't seem to fit. Maybe this could all be rolled into a packaging/distribution tutorial that again follows up QuickWiki.
|
| Migrate for SQLAlchemy |
Efforts are being made to revive the Migrate project and get it working for SQLAlchemy 0.4.x. It's an oft-requested feature, so a little tutorial would be nice once it's mature enough. |
| Sending Email |
FAQ entry or Cookbook. Modules from standard lib, and/or Ben Bangert's extraction of the Django lib.
|
| REST conveniences |
A tutorial in Official Docs showing a simple RESTful service, to highlight Pylons' features that ease such development. The document How map.resource enables controllers as services is great, but it'd be nice if it could be adapted to an example app, cover the REST decorators, and move to Official. |
| Basic Hardening Tips |
Escaping and sanitizing, Mako filters, avoiding XSS and CSRF, WebHelpers' secure_form_tag and the authenticate_form decorator, etc. |
| Cascading template and static paths (think 'skinning') |
The solution cooked up by Yannick Gingras and Jon Rosebaugh (http://urltea.com/2c4a) would make a nice Cookbook tip. (Or see this pylons-discuss group thread ) |
|
|
