Documentationoverhaul

• Create an "advanced" section to contain advanced topics.

• Lead off with a less minimal quick start application, and describe each component briefly while doing so. The current "firstapp.rst" chapter uses a very minimal application configured imperatively. Instead we should use a less minimal application configured using decorators.

  (MO: Please keep the hello app somewhere because the Pyramid/Pylons guide refers to it as an example of a minimal app.)

• Follow up quick start app with a tutorial that goes into more detail. It can be the URL Dispatch wiki tutorial.

• Describe transaction management (pyramid_tm + transaction) in detail.

• Give the debug toolbar its own chapter.

• (Somewhere) list the various branches of Pyramid development (1.0, 1.1, 1.2, and 1.3, etc) and how to install each branch.

• The URL dispatch chapter is very dry and without real-world examples. It should probably contain full application snippets as descriptive examples.

• Currently the "view configuration" and "views" chapters are distinct. This is because we couldn't really figure out a way to introduce view configuration without first introducting view callables, renderers, and templates. A better way to do it might be to defer introducing renderers and templates and combine the views and view configuration chapters into a single chapter that comes before them.

  (MO: +1 but do show a quick example-in-passing with a forward reference
  to the renderer and templates chapters, so that users don't get the
  idea that the minimal usage is the most common usage.)
  

• Add a chapter to the "advanced" section about defining and using custom event types (e.g. maybe move "Using Events" to the advanced section and add an addendum).

• Move "Environment Variables and .ini File Settings" chapter nearer to beginning. That chapter is currently very choppy and needs some fluidity.

• Move "Logging" chapter nearer to beginning.

• Expand "Unit, Integration, and Functional Testing" chapter to include more full examples of using WebTest and possibly selenium. Also put down some more opinionated guidelines about when to use unit test vs. integration/functional tests.

• Describe virtualenv in a more down-to-earth fashion (esp. the "why"). Also describe installation without using a virtualenv, but also warn about the dangers.

• Describe paste ini files in more detail, especially the "why" of them, and how they integrate with an application.

• Describe the whys and wherefores of the "starter" scaffold, including the fact that it's a Python "distribution", which requires a discussion of setuptools.

• Redocument setuptools in context. I don't see another option.

• Steal content from the Pylons docs where appropriate.

• Describe deployment strategies in a more concrete manner. For example, describe deploying with waitress, then describe deploying with gunicorn, then with mod_wsgi.

• Assume URL dispatch until the "Advanced" section.

• Put traversal wiki tutorial, Traversal chapters, and Resources chapter into the "advanced" section.

• Put Security chapter in the Advanced section.

• Add examples of creating concrete authentication policy and authorization policy to Security chapter.

• Put "Combining Traversal and URL Dispatch" into the advanced section.

• Move "Using Hooks" nearer to beginning and make more understandable.

• Move "Pyramid Configuration Introspection" to advanced section.

• Possibly move "Extending an Existing Pyramid Application" and "Advanced Configuration" nearer the beginning, and make more understandable. I don't think these are particularly advanced topics, they're just currently documented poorly.

• Put "Application Configuration" (aka, "configuration.rst", discussion of imperative vs. declarative config) into advanced section and expand.

• Update and move "Startup" and "Request Processing" chapters nearer to end, but not within "advanced". Make these less didactic.

• Spend more time describing packaging, easy_install, pip, and the like. Effectively (and unfortunately) redocument setuptools when describing packaging.

• Assume decorator-based view configuration throughout, put imperative view configuration into advanced section.

• The only code snippet with view classes containing multiple methods seems to be in the view configuration page, in the view_defaults class decorator section.

• Random: it'd be useful to show folks how to stitch applications together using config.include(.., route_prefix='/foo') in a more handholdy way.

• Random: register a notfound view in tutorials, as an example.

• Random: show users how to make a stackable decorators for view callables. For an example, a @login_required decorator (if user is unauthenticated, redirect to login page or raise 401)

• Add descriptions of typical usage patterns for specific functionality in a catalog or Wiki like format, to lower the threshold for new (and advanced) users