Mike Orr avatar Mike Orr committed 3266c2a

Change version to 2.0b1. Delete appendixes and move changes.rst back to
docs directory. Finish 'Usage' chapter.

Comments (0)

Files changed (10)

-2.0 (unreleased)
+2.0b1 (unreleased)
 ----------------
 - Revamp documentation to focus on Pyramid's 'alchemy' scaffold.
 

docs/appendix/changes.rst

-Appendix: Full Changelog
-%%%%%%%%%%%%%%%%%%%%%%%%
-
-.. include:: ../../CHANGES.txt

docs/appendix/no_site_packages.rst

-Appendix: --no-site-packages
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
-The ``--no-site-packages`` option to virtualenv avoids conflicts between Python
-packages inside the virtualenv and possibly-incompatible packages installed
-globally. It's generally recommended for Pyramid. I needed --no-site-packages
-for Ubuntu 10, which uses certain Zope packages in the OS.  ``zope`` is a
-namespace package, and distributions under namespace packages can't be split
-between multiple site-packages directories.  I'm not sure if Ubuntu 11.11 has
-the same limitation.
-
-The tradeoff is that with --no-site-packages, you have to install your own
-packages with C extensions (database libraries, PIL, NumPy, etc) rather
-than relying on the OS packages. Some of these can be difficult to install
-if they involve C. You may be able to get around this by making a symlink
-from the virtulenv's site-packages directory to the global package, but it
-may take some work to make the package happy.

docs/appendix/uninstalling.rst

-Appendix: Uninstalling
-%%%%%%%%%%%%%%%%%%%%%%
-
-To uninstall an application that was installed with "pip install" or "pip
-install -e", run "pip uninstall Zzz". 
-
-If you used easy_install or "python setup.py install" or "python setup.py
-develop" instead of pip, you'll have to uninstall it manually. Chdir to the
-virtualenv's *site-packages* directory. Delete any subdirectories and files
-corresponding to the Python package, its metadata, or its egg link. For our
-sample application these would be *zzz* (Python package), *Zzz.egg-info*
-(pip egg_info), *Zzz.egg* (easy_install directory or ZIP file), and
-*Zzz.egg-link* (egg link file). Also edit *easy-install.pth* and delete
-the application's line if present.
-
+Full Changelog
+%%%%%%%%%%%%%%
+
+.. include:: ../CHANGES.txt
 # The short X.Y version.
 version = '2.0'
 # The full version, including alpha/beta/rc tags.
-release = '2.0'
+release = '2.0b1'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 Akhet
 =====
-:Version: 2.0, released XXXX-XX-XX
+:Version: 2.0b1, released XXXX-XX-XX
 :PyPI: http://pypi.python.org/pypi/Akhet
 :Docs: http://docs.pylonsproject.org/projects/akhet/dev/
 :Source: https://bitbucket.org/sluggo/akhet (Mercurial)
 
 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
+an application scaffold [#]_. Instead, the documentation shows how to customize
 Pyramid's built-in scaffolds to give a Pylons-like environment. The
 documentation focuses on things that either aren't in the Pyramid manual or
 deserve highlighting, and it also discusses the tradeoffs between various
    upgrading
    api
    other_pyramid_features
-
-   appendix/changes
-   appendix/no_site_packages
-   appendix/uninstalling
+   changes
 
 * :ref:`genindex`
 * :ref:`modindex`
 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 1.3 (to be released by the end of 2011), reduces the number
-of built-in scaffolds to three:
+reversal?  Pyramid, in version 1.3 (to be released at the end of 2011 or early
+2012), consolidates the built-in scaffolds to three:
 
 * 'alchemy': URL dispatch + SQLAlchemy
 * 'zodb': traversal + ZODB
 * 'starter': traversal only, no database [#]_
 
-This represents a change of direction for Pyramid. Instead of having scaffolds
-for all combinations of libraries, only the most-used application styles have
-scaffolds. Most people use URL dispatch with SQLAlchemy, and traversal with
-ZODB, so these are the combinations offered. 
+Thus, rather than having scaffolds for all combinations of libraries, Pyramid
+will have scaffolds for just the most widely-used application styles. Most
+people use URL dispatch with SQLAlchemy, and traversal with ZODB, so these are
+the combinations offered.
 
 If you're coming from Akhet 1, or from Pylons/Django/Rails/PHP, use the
-'alchemy' scaffold in Pyramid 1.3 (or the identical 'routesalchemy' scaffold in
-Pyramid 1.2 and earlier, NOT 'alchemy' which is different). 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. 
+'alchemy' scaffold in Pyramid 1.3 (or in Pyramid 1.2, the 'routesalchemy'
+scaffold 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. 
 
 Rant about scaffolds and PasteScript
 ------------------------------------
 
-The main reason the scaffold is gone is that maintaining it turned out to be a
-significant burden. Testing a scaffold requires several manual steps -- every
-time you change a bit of code. Scaffolds aren't inheritable, so you can't just
-specify the differences from an existing scaffold, you have to copy the whole
-thing... and then duplicate any later changes that get made to the original.
-The scaffold API is primitive and limited. 
+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 --
+every time you change a bit of code. Scaffolds aren't inheritable, so you can't
+just specify the differences from an existing scaffold, you have to copy the
+whole thing... and then duplicate any later changes that get made to the
+original.  The scaffold API is primitive and limited; e.g., it has questions
+and variables but they're clumsy. 
 
 The final barrier
 was Python 3. Other packages descended from Paste have been ported to 3
 '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.
 
-.. _[#]: There is discussion about changing 'starter' to URL dispatch,
-   but that had not done as of this writing.
+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.
+
+.. [#] 'starter' might possibly switch to URL dispatch,
+   but it had not done so as of this writing.
 
 .. _Usage: usage.html
+.. _Kotti: http://pypi.python.org/pypi/Kotti
 
 Here are the basic steps to install Pyramid and Akhet, create a virtualenv and
 activate it, create an application, and run it so you can see it in the
-browser.
+browser. The sample application is called "Zzz"; it contains a Python package
+``zzz``.
+
+For Pyramid 1.3 (unreleased; this won't work until it's released):
 
 .. code-block:: sh
-   :linenos:
 
     $ virtualenv --no-site-packages ~/directory/myvenv
     $ source ~/directory/myvenv/bin/activate
-    (myvenv)$ pip install Pyramid
+    (myvenv)$ pip install 'Pyramid>=1.3'
     (myvenv)$ pip install Akhet
     (myvenv)$ pcreate -s alchemy Zzz
     (myenv)$ cd Zzz
     (myenv)$ python setup.py egg_info
     (myenv)$ pserve development.ini
 
-* Line 1 creates the virtualenv. "--no-site-packages" is recommended with
-  Pyramid. `Why <appendix/no_site_packages.html>`_
-* Line 5 creates application "Zzz" based on the 'alchemy' scaffold.
-  (For Pyramid 1.2 and earlier, use "paster create -t routesalchemy Zzz"
-  instead.)
-* Line 7 generates the package metadata (the *Zzz.egg-info*
-  directory). Remember to do this whenever you add or delete files in the
-  package.
-* Line 8 launches the server using the configuration file
-  "development.ini". (For Pyramid 1.2 and earlier, use "paster serve
-  development.ini" instead.)
+For Pyramid 1.2 and earlier:
 
-See the `Installing Pyramid`_ chapter in the Pyramid manual if any of this is
-unfamiliar. 
+.. code-block:: sh
 
-.. 
-    Go to the URL indicated in your web browser (http://127.0.0.1:5000).  The
-    default application doesn't define any tables or models so it doesn't
-    actually do anything except display some help links. When you get bored,
-    press ctrl-C to quit the HTTP.
+    $ virtualenv --no-site-packages ~/directory/myvenv
+    $ source ~/directory/myvenv/bin/activate
+    (myvenv)$ pip install 'Pyramid<1.3'
+    (myvenv)$ pip install Akhet
+    (myvenv)$ paster create -t routesalchemy Zzz
+    (myenv)$ cd Zzz
+    (myenv)$ python setup.py egg_info
+    (myenv)$ paster serve development.ini
 
 Throughout this manual we'll use "Zzz" for your application's name, and ``zzz``
 for the top-level Python module in the application.
 
+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.) 
+
+Remember to re-run the "egg_info" command whenever you add or delete files in
+the application, in order to update the package metadata (*Zzz.egg-info*
+directory). 
+
 See `Uninstalling <appendix/uninstalling.html>`_ if you want to uninstall
 things later.
 
 Using development versions
 ==========================
 
-Akhet's development version works like most Python source repositories.
-Pyramid's development version requires additional work to install.
+Installing Akhet from its source repository works like most Python
+repositories. Pyramid, however, requires additional steps.
 
 .. code-block::  sh
 
+    $ virtualenv --no-site-packages ~/directory/myvenv
+    $ source ~/directory/myvenv/bin/activate
     (myvenv)$ git clone git://github.com/Pylons/pyramid Pyramid
     (myvenv)$ pip install setuptools-git
     (myvenv)$ pip install -e ./Pyramid
     (myvenv)$ hg clone http://bitbucket.org/sluggo/akhet Akhet
     (myvenv)$ pip install -e ./Akhet
+    (myvenv)$ pcreate -s alchemy Zzz
+    (myenv)$ cd Zzz
+    (myenv)$ python setup.py egg_info
+    (myenv)$ pserve development.ini
+
 
 Three things to note here:
 
+* Install Pyramid first so that it will satisfy Akhet's Pyramid dependency.
+  Otherwise when you install Akhet, it will download the latest stable version
+  of Pyramid from PyPI.
 * Pyramid requires 'setuptools-git' because the repsository contains Git
   submodules_.
-* Pyramid *must* be installed as a link (with "-e") because the repository does
-  not contain a MANIFEST.in file, so a regular install wouldn't copy the
-  scaffolds or other supplemental files.
-* Install Pyramid *before* Akhet in order to satisfy the dependency. Otherwise
-  installing Akhet would download the latest stable Pyramid from PyPI.
+* 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.)
 
+Uninstalling
+============
 
-The "p" commands
-================
+To uninstall an application or package that was installed with pip, use "pip
+uninstall":
 
-Pyramid 1.3 includes the following command-line utilities:
+.. code-block:: sh
 
-* **pcreate**: Create a new application using a scaffold.
-* **pserve**: Launch an application and server based on an INI configuration
-  file.
-* **proutes**: List all routes in an application.
-* **pviews**: List all views in an application.
-* **pshell**: An interactive Python shell preloaded with your application
-  environment.
-* **ptweens**: List all tweens.
+   (myvenv)$ pip uninstall Zzz
 
+If you installed it via "easy_install", "python setup.py install", or "python
+setup.py develop", you'll have to uninstall it manually.  Chdir to the
+virtualenv's *site-packages* directory. Delete any subdirectories and files
+corresponding to the Python package, its metadata, or its egg link. For our
+sample application these would be *zzz* (Python package), *Zzz.egg-info* (pip
+egg_info), *Zzz.egg* (easy_install directory or ZIP file), and *Zzz.egg-link*
+(egg link file). Also edit *easy-install.pth* and delete the application's line
+if present.
 
-.. _Pyramid documentation: http://docs.pylonsproject.org/
+
+.. _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
 """
 
 setup(name="Akhet",
-      version="2.0",
+      version="2.0b1",
       description="Pyramid application templates inspired by Pylons 1.",
       long_description=README,
       #long_description=README + "\n\n" +  CHANGES,
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.