Mike Orr  committed 79da587

Finish 'intro' chapter.

  • Participants
  • Parent commits 6acc3bf
  • Branches default

Comments (0)

Files changed (3)

File docs/index.rst

-.. [#] The term "scaffold" has replaced "application template" and "paster
-   template" to avoid confusion with HTML templates. 
+.. [#] The term "scaffold" is the same as "application template", "paster
+   template", and "skeleton". Pyramid has standardized on the term "scaffold"
+   to avoid confusion with HTML templates. 
 .. _Pyramid:

File docs/intro.rst

 Introduction to Akhet 2
-Akhet was created as a bridge between Pylons 1 and Pyramid, for Pylons
-developers who were trying to understand the new framework.  It evolved out of
-a Pyramid/SQLAlchemy application scaffold, gradually adding more Pylons-like
-features and tutorial-level documentation. Now the documentation has taken
-center stage and the scaffold has been retired.  Why this reversal? The
-'akhet' scaffold was widely used and helped programmers get started with Pyramid. But
-scaffolds proved to be difficult to maintain and keep up to date. 
+This is a background chapter on what we learned in Pyramid's first year and
+the reasons behind Akhet 2's changes.
-Now that Pyramid is a
-year old, we can see what application developers are doing after trying both
-Akhet and "raw" Pyramid side by side.  Pyramid itself is evolving, adding
-features and moving away from Paste, and Akhet must evolve along with it. We
-also see users persistently asking for "more tutorials" and raising new
-usage questions.
+Akhet started as a Pyramid/SQLAlchemy application scaffold. It grew more
+Pylons-like features and documentation, until finally the database was just a
+small part of the scaffold. [#]_ In Akhet 2, the documentation takes center
+stage and the scaffold has been retired. Why this reversal? There are four main
-The 'akhet' scaffold (=application template) was widely used and worked well,
-but it was a significant burden to maintain.  
+1. Maintaining a scaffold turned out to be significantly burdensome.
+2. Users' feedback on what they do after they gain experience in both Akhet and
+   "raw" Pyramid. (Many want to mix and match features.)
+3. Pyramid's move away from Paste and PasteScript, which have not been ported
+   to Python 3.
+4. Pyramid users' persistent requests for "more tutorials".
+The first three have to do with the nature of Paste scaffolds. The scaffold API
+is primitive. It doesn't do inheritance, so you can't derive a scaffold by just
+specifying the differences with an existing scaffold: you have to copy the
+entire scaffold, and update it as the original changes. Testing a scaffold
+requires several manual steps to create and run an application every time you
+make a change. "paster create" calls scaffolds "templates", which is confusing
+with HTML templates.
-The 'alchemy' scaffold
+The final barrier was Python 3.  Other packages descended from Paste had been
+ported to 3: PasteDeploy, WebOb.  But nobody volunteered to port Paste and
+PasteScript, especially since the scaffold API needed to be overhauled anyway,
+many of its subcommands were obsolete, and some people questioned the whole
+concept of new plugin subcommands: what exactly was the benefit over simpler
+bin scripts?
+In Pyramid 1.3 [#]_, the developers dropped the Paste and PasteScript
+dependencies, and added bin scripts for the essential utilities Pyramid needs:
+'pcreate', 'pserve', 'pshell', 'proutes', 'ptweens', and 'pviews'. These were
+derived from the Paste code, and the scaffold API is unchanged.
+Pyramid 1.3 reduces the number of built-in scaffolds to three. This is
+good news for new developers because it focuses on the two most-used
+application styles (URL dispatch + SQLAlchemy, or traversal + ZODB), rather
+than on having scaffolds for every little-used permutation of libraries. Akhet
+is following suit by endorsing one of them (called 'alchemy' in Pyramid 1.3,
+and 'routesalchemy' in Pyramid 1.2 and earlier). The differences between
+'alchemy' and 'akhet' are small enough that you can paste in the code yourself
+for the features you want, and there are increasing reasons to do so. 
+1. Some users like to mix and match between Akhet features and other features. 
+2. The 'akhet' scaffold can't absorb every new feature that comes down the
+   block. 
+3.  Pasting the code yourself helps you understand how it's implemented. 
+4. It makes the Akhet maintainer happier because he can sluff the
+   responsibility of maintaining the scaffold onto somebody else who's doing it
+   already, and it will automatically be updated as Pyramid changes.
+The other thing that happened this year is users kept asking for "more
+tutorials". People want more examples of how to get started with their first
+application, how to choose between alternative API styles and libraries, and
+examples of larger integrated applications (with AJAX and the whole hog). This
+Akhet manual won't help with the last one, but it's adding content for the
+first two.
+.. [#] Strictly speaking, the original scaffold was called 'pyramid_sqla', as
+   was the distribution. It was renamed to Akhet to show it wasn't primarily
+   about SQLAlchemy. Also because of a general decision to give
+   third-party scaffolds their own identity rather than pyramid_something.
+.. [#] Pyramid 1.3 was in development as of November 2011. It's expected to be
+   released in December or soon thereafter.
+.. _Usage: usage.html

File docs/vocabulary.rst

     A function or method equivalent to a Pylons controller action. It takes a
     ``Request`` object representing a web request, and returns a ``Response``
-    object.  (In Akhet the view's arguments and return value are different
-    than this because of handlers and renderers.)
+    object.  (The return value may be different when using a renderer.)
-Handler (View Handler)
+View Class (Handler)
     A class containing view methods, so equivalent to a Pylons controller.
-    Handlers are defined in the ``pyramid_handlers`` package and are
-    documentated there.
+    If the view is a method rather than a function, the ``request`` argument is
+    passed to the class constructor rather than to the method. The
+    ``pyramid_handlers`` package offers one Pylons-like way to define and
+    register view classes.
     split is more useful: the *model* which is all code specific to your
     business and can be used on its own, and the *view* which is all code
     specific to the framework, user interface, and HTTP/HTML environment.
+    (The "controller" then is the framework itself.)
 URL Dispatch
     In URL dispatch, the context is normally the same as the root, an
     unimportant default object. However, you can override the context on a
-    per-route basis to provide authorization information.
+    per-route basis to provide authorization information or data objects.