Anonymous avatar Anonymous committed 74b0ded

Docs.

Comments (0)

Files changed (6)

-dev (unreleased)
+1.0 (unreleased)
 ----------------
 - App skeleton:
 
   + Simplify home page and add a Mako site template that can be easily
     extended by the user.
+  + New default layout and stylesheet by Marcin Lulek (Ergo^), designed to
+    be extensible and a learning tool.
+  + Separate industry-standard "reset" stylesheet for cross-browser
+    consistency.
   + Add "flash message" demo to home page.
+  + "Requirements" file for easy installation of dependencies.
 
 1.0b2 (2011-03-19)
 ------------------

docs/architecture.rst

     debug_routematch = false
     debug_templates = true
     default_locale_name = en
+    cache.regions = default_term, second, short_term, long_term
+    cache.type = memory
+    cache.second.expire = 1
+    cache.short_term.expire = 60
+    cache.default_term.expire = 300
+    cache.long_term.expire = 3600
     mako.directories = zzz:templates
-    sqlalchemy.url = sqlite:///%(here)s/db.sqlite
+    mako.strict_undefined = true
     session.type = file
     session.data_dir = %(here)s/data/sessions/data
     session.lock_dir = %(here)s/data/sessions/lock
     session.key = Zzz
-    session.secret = 4b391beb818275e9aef4a58207782e5366e9c662
+    session.secret = 3f4c8f62600a4edda7026f0ce13befbccd8bbcdb
+    sqlalchemy.url = sqlite:///%(here)s/db.sqlite
 
 .. code-block:: ini
 
 Akhet
 =====
-:Version: 1.0b2, released 2010-03-19
+:Version: 1.0, released 2011-XX-XX
 :PyPI: http://pypi.python.org/pypi/Akhet
-:Docs: http://sluggo.scrapping.cc/python/Akhet/
+:Docs: http://docs.pylonsproject.org/projects/akhet/dev/
 :Source: https://bitbucket.org/sluggo/akhet (Mercurial)
+:Bugs: https://bitbucket.org/sluggo/akhet/issues
+:Discuss: pylons-discuss_ list
 
 
 **Akhet** is a Pylons-like application template (or "skeleton") for the
 Coming soon: tutorials for new web developers, and a higher-level skeleton with
 more batteries. These are being written by third parties.
 
-Akhet version 1.0b2 is a beta version to give it some use in test apps before
-the final release. Changes in 1.0b2:
-
-* Bugfix in URLGenerator.
-* Add Beaker cache configuration.
-
-Please send feedback to the pylons-discuss_ list, and report bugs on
-the `bug tracker`_. Akhet was previously called "pyramid_sqla"; it was changed
-to reflect its evolution from a SQLALchemy application skeleton to a more
-full-fledged Pylons-like skeleton.  The SQLAlchemy library from pyramid_sqla
-was spun off to the "SQLAHelper" package.
-
-The word "akhet" is the name of the hieroglyph that is Pylons' icon: a sun
-shining over two pylons. It means "horizon" or "mountain of light".
-
-Akhet was developed on Python 2.6 and Ubuntu Linux 10.10. Pyramid runs on
-Python 2.4 - 2.7; Mac, Windows, Unix; CPython, Jython, and Google App Engine.
-It does not run on Python 3 yet; several dependencies need to be updated for
-that.
-
 .. _Pyramid: http://docs.pylonshq.com/pyramid/dev/
 .. _pylons-discuss: http://groups.google.com/group/pylons-discuss
-.. _bug tracker: https://bitbucket.org/sluggo/akhet/issues
 
 Features
 --------
   (You can also choose your own template globals.)
 * "handlers", "models", and "lib" are packages to give plenty of room for large
   applications.
+* An extensible home page template, site template, and default stylesheet.
 
 
 Documentation
    bugs
    changes
 
-Indices and tables
-------------------
-
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
 
+
+Akhet was previously called "pyramid_sqla"; it was changed
+to reflect its evolution from a SQLALchemy application skeleton to a more
+full-fledged Pylons-like skeleton.  The SQLAlchemy library from pyramid_sqla
+was spun off to the "SQLAHelper" package.
+
+The word "akhet" is the name of the hieroglyph that is Pylons' icon: a sun
+shining over two pylons. It means "horizon" or "mountain of light".
+
+Akhet was developed on Python 2.6 and Ubuntu Linux 10.10. Pyramid runs on
+Python 2.4 - 2.7; Mac, Windows, Unix; CPython, Jython, and Google App Engine.
+It does not run on Python 3 yet; several dependencies are being updated for
+that.
 
     $ paster create -t akhet Zzz
 
-This is how you create a new application. Our sample application is named
-"Zzz". It will ask whether to preconfigure SQLAlchemy in the application; the
+This is how you create a new application, as described earlier in the Usage
+chapter. Our sample application is named "Zzz". It will ask certain questions.
+Currently it asks whether to preconfigure SQLAlchemy in the application; the
 default is true. Answer 'n' to skip SQLAlchemy. You can also pass the answer on
 the command line:
 
     $ paster create -t akhet Zzz sqlalchemy=n
 
 The SQLAlchemy question is specific to the 'akhet' application skeleton. Other
-skeletons may have other questions or no questions. (We use the phrase
-"skeleton" rather than the traditional "application template" because the
-latter is ambiguous and can be confused with a template file.) 
+skeletons may have other questions or no questions. (Paster calls the
+application skeleton a "template" but we avoid that term because it can be
+confused with a template file.)
 
-The **application name** must be a valid Python identifier. I.e., it must start
-with a letter or underscore; and may contain only letters, numbers, and
-underscore. "paster create" will automatically generate the Python **package
-name** by lowercasing the application name. 
-
-You can't use an application name that's identical to a module in the Python
-standard library.  Paster will create it but Python won't be able to run it. So
-don't name your application "Test".
 
 paster serve
 ------------
 
-**paster serve** also works the same:
+**paster serve** also works the same as in Pylons:
 
 .. code-block:: sh
 
 
 **paster proutes** prints the current route definitions. You have to specify
 both the INI file and the application section in the file, which for Akhet is
-"zzz" regardless of the actual application name:
+"myapp" regardless of the actual application name:
 
 .. code-block:: sh
 
-    $ paster proutes development.ini zzz
+    $ paster proutes development.ini myapp
 
 This replaces "paster routes" in Pylons.
 
 It replaces "paster shell" in Pylons.
 
 "paster make-config" is not supported in Pyramid. Instead, all Pyramid
-skeletons include a production.ini. You can copy it to make other
+skeletons include a *production.ini*. You can copy it to make other
 INI files.
 
 "paster setup-app" is not supported in Pyramid. Instead, Akhet includes a
-*create_db* script. After you have defined your models, run it to create the
-database tables. You can customize the script if you want to prepopulate the
-dataabse with certain initial records:
+*create_db.py* script. After you have defined your models, run it to create the
+database tables:
 
 .. code-block:: sh
 
     $ python -m zzz.scripts.create_db development.ini
 
+You can customize the script if you want to prepopulate the
+databse with certain initial records.
 You can also put other utility scripts in the "scripts" package and run them
 the same way.
 
 in Ubuntu Linux 10.10: python-setuptools, python-virtualenv, and
 virtualenvwrapper.
 
-You'll probably want Virtualenv's ``--no-site-packages`` option to avoid
-undesired interactions with with other Python packages installed globally
-(outside the virtualenv). In particular, "zope" is a namespace package that
-can't be split between the global site-packages and the virtualenv. Ubuntu
-installs some Zope packages and that can lead to ImportError unless you use
-``--no-site-packages``. If you do need particular global packages (such as those
-with C dependencies that can be hard to install yourself), make symbolic links
-from the virtualenv's site-packages to the packages in the global
-site-packages.
-
 .. code-block:: sh
 
     $ virtualenv --no-site-packages ~/directory/myvenv
     (myvenv)$ pip install Akhet
     ...
 
+You'll probably need Virtualenv's ``--no-site-packages`` option as above to
+avoid undesired interactions with with other Python packages installed globally
+(outside the virtualenv). I had particular trouble due to some Zope packages
+Ubuntu installs by default. If you need certain global packages (e.g., those
+with C dependencies that can be hard to install yourself), make symbolic links
+to them in the virtualenv's site-packages.
+
+
 Creating an application
 =======================
 
 
 .. code-block:: sh
 
-    (myvenv)$ paster create -t akhet MyApp
+    (myvenv)$ paster create -t akhet Zzz
         Selected and implied templates:
       Akhet#akhet  A Pylons-like Pyramid project
 
     Running /home/sluggo/.virtualenvs/pyramid/bin/python setup.py egg_info
     (myvenv)$ 
 
-**Then install the application to pull in the dependencies it needs.** (These
-dependencies aren't installed with Akhet itself because they're different for
-different applications.) There are several ways to do this: "python setup.py
-develop", "pip install -e .", and "pip install .", and "python setup.py
-install" :
+You can answer the question on the command line so that it won't prompt you:
 
 .. code-block:: sh
 
-    (venv)$ cd Zzz
-    (venv)$ pip install -e .
+    (myvenv)$ paster create -t akhet Zzz sqlalchemy=y
 
-(A few systems don't work with the "-e" option or "python setup.py develop".
-If you get an ImportError on "Zzz", try installing it again without the "-e".
-My home computer does this but none of my other computers.)
+Our sample application is called "Zzz". It has a top-level directory "Zzz"
+containing a Python package ``zzz`` (lowercase). Throughout this manual we'll
+use Zzz and zzz as shorthands for your application name and package name. You
+can name your application anything, but don't use "Test" or any other name in
+the Python standard library, otherwise it won't run. It's easiest to stick with
+a valid Python identifier: a letter or underscore followed by zero or more
+letters, numbers, or underscores.
 
-It should work out of the box now:
+Install the application's dependencies. For convenience these are listed both
+in a *requirements.txt* file and in *setup.py*.
+
+.. code-block:: sh
+
+    (myvenv)$ cd Zzz
+    (myvenv)$ pip install -r requirements.txt
+    ...
+
+Generate the package's metadata ("egg_info" files):
+
+.. code-block:: sh
+
+    (myvenv)$ python setup.py egg_info
+    running egg_info
+    writing requirements to Zzz.egg-info/requires.txt
+    writing Zzz.egg-info/PKG-INFO
+    writing top-level names to Zzz.egg-info/top_level.txt
+    writing dependency_links to Zzz.egg-info/dependency_links.txt
+    writing entry points to Zzz.egg-info/entry_points.txt
+    writing paster_plugins to Zzz.egg-info/paster_plugins.txt
+    reading manifest file 'Zzz.egg-info/SOURCES.txt'
+    writing manifest file 'Zzz.egg-info/SOURCES.txt'
+
+.. tip::
+
+    Whenever you run the application, re-run this command first *if* you've
+    added/deleted any files or modified *setup.py*. You do not have to re-run
+    it if you've merely modified the files.
+
+The application should now run out of the box:
 
 .. code-block:: sh
 
 actually do anything except display some help links. When you get bored, press
 ctrl-C to quit the HTTP.
 
-Building an application
-=======================
+Building the application
+========================
+
+You can now customize the application as you see fit.
 
 If you've never built a (Pylons) web application before, there will be
 Akhet-specifc tutorials coming but they're not finished yet. In the meantime,

docs/vocabulary.rst

 
 Router
 
-    A Pyramid WSGI application, an instance of ``pyramid.router.Router``.
-    Equivalent to ``PylonsApp``.
+    A Pyramid WSGI application, which is an instance of
+    ``pyramid.router.Router``.  Equivalent to ``PylonsApp``.
 
 View (View Callable)
 
     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 because of
-    handlers and renderers.)
+    ``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.)
 
 Handler (View Handler)
 
 MVC
 
     The Model-View-Controller pattern used in programming. Pyramid is more of a
-    MV (Model-View) framework than MVC. Many contemporary web developers --
-    while still supporting the basic principle of keeping your business
-    logic separate from your user interface code -- have given up on the formal
-    categories of MVC as not being well suited to the web.  MVC envisions a
+    MV (Model-View) framework than MVC. Many contemporary web developers have
+    given up on MVC as not being well suited to the web.  MVC envisions a
     three-way split between business logic, user interface, and framework
-    interface, but in practice the latter two are hard to separate. MVC was
-    invented in the 1980s to separate application code from low-level
-    keyboard drivers and video drivers, a situation not directly applicable to
-    modern web development.
+    interface, but in practice the latter two are hard to separate. A two-way
+    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.
 
 URL Dispatch
 
 Traversal
 
     Pyramid's other routing mechanism, which looks up a view and a context by
-    matching the URL to a node in a resource tree.  Many Akhet applications do
-    not use traversal, and the Akhet docs don't cover how to use it.
-    Nevertheless, we'll briefly explain what it is.
+    matching the URL to a node in a resource tree.  Most simple Akhet
+    applications do not use traversal, and this manual does not cover how to
+    use it.  Nevertheless, we'll briefly explain what it is.
 
     Traversal is especially suited to situations where URLs can be arbitrarily
     deep in ways that are unknown at application startup, such as a CMS system
 Resource Tree, Root, Resource
 
     In traversal, a *resource tree* is a nested dict-like structure such as a
-    ZODB database or a group of nested dicts. The outermost container object is
-    the *root*. Each value in the nested dicts is a *resource*.
+    ZODB object database or a group of nested dicts. The outermost container
+    object is the *root*. Each value in the nested dicts is a *resource*.
 
     In URL dispatch, the *root* can be any object. Normally you don't specify
-    it, and the system provides a default root.
+    it, and Pyramid provides a default root.
 
 Context
 
 
 Request
 
-    A subclass of WebOb.Request which contains all state data pertinent to the
-    current request and the application runtime. Its attributes subsume the
-    functionality of several Pylons globals (request, response, session,
-    tmpl_context or c, url), the match dict, query parameters, etc. 
+    An object which contains all state data pertinent to the current web
+    request and the application runtime. It's a subclass of ``WebOb.Request``.
+    Its attributes subsume the functionality of several Pylons globals
+    (request, response, session, tmpl_context or c, url), the match dict, query
+    parameters, etc. 
 
 Response
 
-    A subclass of WebOb.Response, or any object with the same ``status``,
-    ``headerlist`` and ``app_iter`` attributes that a Response has.  
+    An object which specifies what kind of response to return to the user:
+    the HTTP status, HTTP headers, and body content. It's normally a subclass
+    of ``WebOb.Response`` but you can substite any object with the appropriate
+    ``status``, ``headerlist``, and ``app_iter`` attributes.
     A view must return a Response unless it's using a renderer.
 
 Renderer
 
     An object that is global to the application and contains internal framework
     data such as which routes and views have been defined. Application writers
-    generally ignore it except when they need a setting, which are in the
+    generally ignore it except when they need a setting, which are in its
     ``.settings`` attribute.
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.