Commits

Mike Orr  committed 1269789

Focus docs on Wiki2 tutorial, add a scaffolds table, and move the scaffolds
rant to an appendix.

  • Participants
  • Parent commits fcb9316

Comments (0)

Files changed (6)

File docs/architecture.rst

 .. _MultiDict API: api.html#multidict
 .. _API: api.html
 .. _minimal application: http://docs.pylonsproject.org/projects/pyramid/en/1.2-branch/narr/firstapp.html
-.. _asset syntax:
-http://docs.pylonsproject.org/projects/pyramid/en/1.2-branch/narr/assets.html#asset-specifications
+.. _asset syntax: http://docs.pylonsproject.org/projects/pyramid/en/1.2-branch/narr/assets.html#asset-specifications

File docs/index.rst

 Akhet is a set of tutorial-level documentation and convenience code for
 Pyramid_. Version 2 focuses more heavily on documentation, and does not contain
 an application scaffold [#]_. Instead the documentation shows how to customize
-Pyramid's built-in 'alchemy' scaffold to give a Pylons-like environment. The
-documentation walks through the default application's structure,
-highlighting Useful Bits of Information that are buried in the Pyramid manual
-or are not in the manual.  It also discusses some alternative APIs and the
+Pyramid's built-in scaffolds to give a Pylons-like environment. The
+documentation walks through the default application's structure, providing a
+supplement to the Pyramid documentation and showing how the structure differs
+from Pylons.  It also discusses some alternative APIs and the
 tradeoffs between them. The Akhet library (the convenience classes) are
 unchanged in this release.
 
    other_pyramid_features
    changes
    unfinished
+   rant_scaffold
 
 * :ref:`genindex`
 * :ref:`modindex`

File docs/intro.rst

 Introduction to Akhet 2
 %%%%%%%%%%%%%%%%%%%%%%%
 
-This chapter discusses Akhet's history and current status. The next chapter
+This chapter recounts Akhet's history and current status. The next chapter
 introduces some vocabulary terms. The third chapter summarizes how to create a
 Pyramid application using the recommended skeleton, and how to use the Pyramid
 and Akhet development versions. The subsequent chapters analyze different
 more Pylons-like features, a small library, and documentation that
 expanded to become a general introduction to Pyramid.  In Akhet 2, the
 documentation takes center stage and the scaffold has been retired. Why this
-reversal?  Pyramid, in version 1.3 (to be released at the end of 2011 or early
-2012), consolidates the built-in scaffolds to three:
+reversal?  Mainly because it's so much work to maintain a scaffold. (The
+`scaffold rant`_ appendix has the full details.) Also, Pyramid 1.3 consolidates
+the built-in scaffolds to three well-chosen ones.
 
-* 'alchemy': URL dispatch + SQLAlchemy
-* 'zodb': traversal + ZODB
-* 'starter': URL dispatch only, no database
+=================    ==========  ====================    ====================
+Routing mechanism    Database    Pyramid 1.3 scaffold    Pyramid 1.2 scaffold
+=================    ==========  ====================    ====================
+URL dispatch         SQLAlchemy  **alchemy**             routesalchemy
+URL dispatch         \-          **starter**             \-
+Traversal            ZODB        **zodb**                zodb
+Traversal            SQLAlchemy  \-                      alchemy
+Traversal            \-          \-                      starter
+=================    ==========  ====================    ====================
 
-Thus, Pyramid 1.3 focuses on the two most widely-used application styles,
-rather than on having scaffolds for all possible combinations of libraries.
-Most people use URL dispatch with SQLAlchemy, and traversal with ZODB, so these
-are the combinations offered.
+The Pyramid 1.3 scaffolds emphasize on the two most widely-used application
+styles: URL dispatch with SQLAlchemy, and traversal with ZODB. The scaffold
+names are simplified to focus on this goal. The 'starter' scaffold switches to
+URL dispatch because it's more appropriate for beginners. Using traversal at
+all is an advanced topic, and especially with SQLAlchemy.  (If you want to see
+how traversal with SQLAlchemy can be implemented robustly, check out the Kotti_
+content-management system.) 
 
-If you're coming from Akhet 1, or from Pylons/Django/Rails/PHP, use the
-'alchemy' scaffold in Pyramid 1.3 (or the 'routesalchemy' scaffold in Pyramid
-1.2, which is identical). Then read on to see how to customize the application
-to add all the features Akhet 1 had. Each feature requires pasting in only a
-few lines of code, and by doing it yourself you'll get a better feel of how
-it's implemented and what it's doing. 
+For those coming from Akhet 1, Pylons, Django, Rails, and similar frameworks
+with something akin to Routes, URL dispatch and SQL databases will be familiar.
+For those coming from a Java servlet or PHP-without-a-framework background, URL
+dispatch will be new but it's a good rule-based way to handle URLs. Traversal
+is an entirely different concept, which is most useful when site users are
+allowed to create their own URLs with multiple levels (as in a
+content-management system or file manager). Traversal maps naturally to nested
+objects, which is why it's often paired with an object database. 
 
-Rant about scaffolds and PasteScript
-------------------------------------
+So this Akhet book and the Pyramid developers both recommend that new users
+start with the 'alchemy' or 'starter' scaffold in Pyramid 1.3, or the
+'routesalchemy' scaffold in Pyramid 1.2. The rest of this book is based on
+those scaffolds. 
 
-The main reason the 'akhet' scaffold is gone is that maintaining it turned out
-to be a significant burden. Testing a scaffold requires several manual steps --
-change a line of code, generate an app, install it, test a URL, test some other
-URLs, change the application, backport the change to the scaffold, generate
-another app, install and test it, -OR- make changes directly to the scaffold
-and generate an app to see whether it works. If it requires custom application
-code to trigger the bug, you have to re-apply the code every time you crete the
-app. Beyond that, Pyramid evolves over time, so the scaffolds have to be
-updated even if they were working OK. And the scaffold API is primitive and
-limited; e.g., you can't inherit from a scaffold and specify just the changes
-between yours and the parent.
+Two other changes in Pyramid 1.3 deserve mention. One, it's compatible with
+Python 3, and it drops Python 2.5 support. Akhet 2.0 does not do either of
+these yet, but the next version probably will.
 
-The final barrier
-was Python 3. Other packages descended from Paste have been ported to 3
-(PasteDeploy, WebOb), but Paste and PasteScript haven't been. There doesn't
-seem to be much point because the scaffold API needs to be overhauled anyway,
-many of paster's subcommands are obsolete, and some people question the whole
-concept of plugin subcommands: what exactly is its benefit over bin scripts?
+Two, as part of the Python 3 porting, Pyramid 1.3 dropped its Paste and
+PasteScript dependencies. These will probably not be ported to 3 for reasons
+listed in the `scaffold rant`_. This has the following consequences:
 
-Pyramid 1.3 drops the Paste and PasteScript
-dependencies, and adds 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.
+* The 'paster' command is gone. It's replaced by 'pcreate' and 'pserve'.
+* The default HTTP server is now Wsgiref, the one in the Python standard
+  library. You can use it during development and switch to a more robust
+  server for production (PasteHTTPServer, CherryPy, mod_wsgi, FastCGI, etc).
+* PasteDeploy is <i>not</i> dropped, so the INI files still work the same way.
 
-Two other factors led to the demise of the scaffold. One, users wanted to mix
-and match Akhet features and non-Akhet features, and add databases to the
-scaffold (e.g., MongoDB). That would lead to more questions in the scaffold, or
-more scaffolds, and more testing burden (especially since I didn't use those
-databases). 
 
-The other factor is, I began to doubt whether certain Akhet features are
-necessarily better than their non-Akhet conterparts. For instance, Akhet 1 and
-Pyramid have different ways of handling static files. Each way has its pluses
-and minuses. Akhet's role is to make the Pylons way available, not to recommend
-it beyond what it deserves.
-
-So faced with the burden of maintaining the scaffold and keeping it updated, I
-was about to retire Akhet completely, until I realized it could have a new life
-without the scaffold. And as I work on my own applications and come up with new
-pieces of advice or new convenience classes, I need a place to put them, and
-Akhet 2 is an ideal place. So viva the new, scaffold-free, Akeht 2.
-
-
-.. _Usage: usage.html
 .. _Kotti: http://pypi.python.org/pypi/Kotti
+.. _scaffold rant: rant_scaffold.html

File docs/rant_scaffold.rst

+Appendix: Rant about Scaffolds and PasteScript
+----------------------------------------------
+
+The main reason the 'akhet' scaffold is gone is that maintaining it turned out
+to be a significant burden. Testing a scaffold requires several manual steps --
+change a line of code, generate an app, install it, test a URL, test some other
+URLs, change the application, backport the change to the scaffold, generate
+another app, install and test it, -OR- make changes directly to the scaffold
+and generate an app to see whether it works. If it requires custom application
+code to trigger the bug, you have to re-apply the code every time you crete the
+app. Beyond that, Pyramid evolves over time, so the scaffolds have to be
+updated even if they were working OK. And the scaffold API is primitive and
+limited; e.g., you can't inherit from a scaffold and specify just the changes
+between yours and the parent.
+
+The final barrier
+was Python 3. Other packages descended from Paste have been ported to 3
+(PasteDeploy, WebOb), but Paste and PasteScript haven't been. There doesn't
+seem to be much point because the scaffold API needs to be overhauled anyway,
+many of paster's subcommands are obsolete, and some people question the whole
+concept of plugin subcommands: what exactly is its benefit over bin scripts?
+
+Pyramid 1.3 drops the Paste and PasteScript
+dependencies, and adds 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.
+
+Two other factors led to the demise of the scaffold. One, users wanted to mix
+and match Akhet features and non-Akhet features, and add databases to the
+scaffold (e.g., MongoDB). That would lead to more questions in the scaffold, or
+more scaffolds, and more testing burden (especially since I didn't use those
+databases). 
+
+The other factor is, I began to doubt whether certain Akhet features are
+necessarily better than their non-Akhet conterparts. For instance, Akhet 1 and
+Pyramid have different ways of handling static files. Each way has its pluses
+and minuses. Akhet's role is to make the Pylons way available, not to recommend
+it beyond what it deserves.
+
+So faced with the burden of maintaining the scaffold and keeping it updated, I
+was about to retire Akhet completely, until I realized it could have a new life
+without the scaffold. And as I work on my own applications and come up with new
+pieces of advice or new convenience classes, I need a place to put them, and
+Akhet 2 is an ideal place. So viva the new, scaffold-free, Akeht 2.

File docs/usage.rst

-Creating an Application and Using Development Versions
+Installing Pyramid and Creating Applications
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
-Creating a Pyramid application
-==============================
+Here are the basic steps to install Pyramid and Akhet and create an
+application. For more details see the `Installing Pyramid`_ and `Creating a
+Pyramid Project`_ chapters in the Pyramid manual.  New users should also do
+the `SQLAlchemy + URL Dispatch Wiki Tutorial`_, which explains Pyramid while
+you build a simple wiki application. 
 
-Here are the basic steps to install Pyramid and Akhet, create a virtualenv,
-create an application using the recommended 'alchemy' scaffold, and run it in
-your web browser. The steps are effectively the same as the installation
-chapter in Pyramid's `Wiki2 tutorial`_; I'm just using pip more for
-installation.  
+The steps here are effectively the same as
+the installation chapter of the Wiki tutorial; we're just using pip rather than
+other installation commands because it makes uninstallation easier, and because
+it's the `new hotness`_. We also activate the virtualenv_, which allows us to
+keep the application source outside the virtualenv without having to type
+convoluted paths to run virtualenv commands. Keeping the application outside
+the virtualenv makes it easier to delete/recreate the virtualenv if it gets
+hosed, and to run the application under multiple virtualenvs (e.g., to see how
+it works under different Python versions, different Pyramid versions, and
+different dependency versions). 
 
-Our sample application is called "Zzz"; it contains a Python package ``zzz``.
-A prebuilt tarball is available: Zzz.tar.gz_ [#]_.  The following chapters
-will walk through this default application.
+Our sample application is called "Zzz"; it contains a Python package ``zzz``. A
+prebuilt tarball is available: Zzz.tar.gz_ [#]_.  The following chapters will
+walk through this default application.
 
-For Pyramid 1.3 (unreleased; this won't work until it's released):
+These steps assume you have Python, virtualenv_, and SQLite_ installed.
+
+Creating an application with Pyramid 1.3 and Akhet
+==================================================
+
+(Pyramid 1.3 is unreleased as of this writing. This alternative won't work
+until it's released, so use one of the other two alternatives instead.)
 
 .. code-block:: console
 
     (myenv)$ populate_Zzz development.ini
     (myenv)$ pserve development.ini
 
-For Pyramid 1.2 and earlier:
+
+Creating an application with Pyramid 1.2 and Akhet
+==================================================
 
 .. code-block:: console
 
     (myenv)$ populate_Zzz development.ini
     (myenv)$ paster serve development.ini
 
-The "--no-site-packages" option is recommended for Pyramid; it isolates the
-virtualenv from packages installed globally on the computer, which may be
-incompatible or have conflicting versions. If you have trouble installing a
-package that has C extensions (e.g., a database library, PIL, NumPy), you can
-try making a symlink from the virtualenv's site-packages directory to the OS
-version of the package; it may take some jiggering to make the package happy.
 
-(I found --no-site-packages necessary on Ubuntu 10, because Ubuntu installs
-some Zope packages but not all the ones Pyramid needs, and ``zope`` is a
-namespace package which can't be split between the global directory and the
-virtualenv.) 
-
-"pip install -e ." installs the application and all dependencies listed in
-setup.py. This is necessary with the 'akhet' scaffold to install SQLAlchemy.
-In a simpler application with no dependencies, you can get by with just running
-"python setup.py egg_info" (which updates the distribution metadata without
-installing the distribution) *if* you always chdir to the application's
-directory before running it.
-
-Remember for later: whenever you add or delete a file in the application
-directory, run "python setup.py egg_info" to update the metadata.
-
-See `Uninstalling <appendix/uninstalling.html>`_ if you want to uninstall
-things later.
-
-Using development versions
-==========================
+Creating an application with development versions of Pyramid and Akhet
+======================================================================
 
 Installing Akhet from its source repository works like most Python
 repositories. Pyramid, however, requires additional steps.
 * Pyramid *must* be installed as a link (with "-e") because a regular install
   won't copy the scaffolds or other supplemental files. (That's because the
   repository does not contain a MANIFEST.in file.)
+* The extra "./" is so that "pip install -e" recognizes the argument as a path
+  name rather than as something to download from PyPI.
+
+
+Observations
+============
+
+The "--no-site-packages" option is recommended for Pyramid; it isolates the
+virtualenv from packages installed globally on the computer, which may be
+incompatible or have conflicting versions. If you have trouble installing a
+package that has C extensions (e.g., a database library, PIL, NumPy), you can
+try making a symlink from the virtualenv's site-packages directory to the OS
+version of the package; it may take some jiggering to make the package happy.
+
+I found --no-site-packages necessary on Ubuntu 10 because Ubuntu installs
+some Zope packages but not all the ones Pyramid needs, and ``zope`` is a
+namespace package which can't be split between the global directory and the
+virtualenv. I have not had this problem with Ubuntu 11.10 so far, so it may be
+fixed.
+
+"pip install -e ." installs the application and all dependencies listed in
+setup.py. That's necessary for this application because it depends on
+SQLAlchemy, which is not installed with raw Pyramid. Installation also sets up
+the 'populate_Zzz' command. In a simpler application without these restrictions
+(such as the 'starter' scaffold), you can get by without installation. You'll
+have to run "python setup.py egg_info" instead (which updates the
+distribution's metadata, and is one of the installation steps. Also, if you
+don't install the application, you'll have to always chdir to the application's
+directory before running it, because Python won't be able to import it
+otherwise.
+
+**Remember for later:** whenever you add or delete a file in the application
+directory, run "python setup.py egg_info" to update the metadata.
+
+See `Uninstalling <appendix/uninstalling.html>`_ if you want to uninstall
+things later.
 
 Uninstalling
 ============
 
-To uninstall an application or package that was installed with pip, use "pip
+To uninstall an application or package that was installed via pip, use "pip
 uninstall":
 
 .. code-block:: console
    (Linux). 
 
 
-.. _Pyramid documentation: http://docs.pylonsproject.org/en/latest/docs/pyramid.html
-.. _Pyramid tutorials: http://docs.pylonsproject.org/projects/pyramid_tutorials/dev/
 .. _virtualenv: http://pypi.python.org/pypi/virtualenv
-.. _Installing Pyramid: http://docs.pylonsproject.org/projects/pyramid/1.0/narr/install.html
+.. _SQLite: http://sqlite.org
 .. _submodules: http://schacon.github.com/git/git-submodule.html
 .. _Zzz.tar.gz: _static/Zzz.tar.gz
-.. _Wiki2 tutorial: http://docs.pylonsproject.org/projects/pyramid/en/latest/tutorials/wiki2/installation.html
+.. _Installing Pyramid: http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/install.html
+.. _Creating a Pyramid Project: http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/project.html
+.. _SQLAlchemy + URL Dispatch Wiki Tutorial: http://docs.pylonsproject.org/projects/pyramid/en/latest/tutorials/wiki2/installation.html
+.. _new hotness: http://python-distribute.org/pip_distribute.png

File docs/vocabulary.rst

 Pyramid Vocabulary
 %%%%%%%%%%%%%%%%%%
 
+This is a supplement to the Glossary_ in the Pyramid manual. It focuses on the
+subset of terms critical for Akhet, and compares them to Pylons.
+
+
 Router
 
     A Pyramid WSGI application, which is an instance of
     data such as which routes and views have been defined. Application writers
     generally ignore it except when they need a setting, which are in its
     ``.settings`` attribute.
+
+
+.. _Glossary: http://docs.pylonsproject.org/projects/pyramid/en/latest/glossary.html