Lots of updates, move more code out of code-blocks into working package code. About to tackle cool Pyramid stuff.

38 files changed, 323 insertions, 244 deletions

diff --git a/docs/getting_started/databases.rst b/docs/getting_started/databases.rst
index f982643af..c415ed2db 100644
--- a/docs/getting_started/databases.rst
+++ b/docs/getting_started/databases.rst
@@ -2,3 +2,20 @@
 Databases With SQLAlchemy
 =========================
 
+We can now visit our sample at
+`http://localhost:6543/ <http://localhost:6543/>`_. Some choices that
+the scaffold helped us with:
+
+- A ``setup.py`` with appropriate dependencies
+
+- Connection strings and integration in our ``development.ini`` file
+
+- A console script which we ran above to initialize the database
+
+- The SQLAlchemy engine integrated into the ``Configurator`` on
+  application startup
+
+- Python modules for the SQLAlchemy models and the Pyramid views that
+  go with them
+
+- Some unit tests...yummy!
diff --git a/docs/getting_started/index.rst b/docs/getting_started/index.rst
index 06baf20ca..b7ab3c7bb 100644
--- a/docs/getting_started/index.rst
+++ b/docs/getting_started/index.rst
@@ -29,6 +29,12 @@ Notes
 
 - Cover static urls and asset specifications, resolving, replacing
 
+.. toctree::
+   :maxdepth: 1
+
+   gettingstarted
+
+
 Contents
 ========
 
@@ -42,6 +48,7 @@ Contents
    views
    templates
    static_assets
+   pserve
    testing
    forms
    databases
diff --git a/docs/getting_started/pserve.rst b/docs/getting_started/pserve.rst
new file mode 100644
index 000000000..a7f8ba62c
--- /dev/null
+++ b/docs/getting_started/pserve.rst
@@ -0,0 +1,18 @@
+===================================
+Application Running With ``pserve``
+===================================
+
+
+Three Cool Things About ``pserve``
+----------------------------------
+
+1. *Multiple .ini files*. You might have some settings in
+   development mode or some in production mode. Maybe you are writing an
+   add-on that needs to be wired-up by other people.
+
+2. *Choice of WSGI server*. ``pserve`` itself isn't a WSGI server.
+   Instead, it loads the server you want from the configuration file.
+
+3. *Friends of pserve*. With the ``pserve``/``.ini`` approach you
+   also get other commands that help during development: ``pshell``,
+   ``proutes``, ``pviews``, ``prequest``, etc.
diff --git a/docs/getting_started/quick_glance.rst b/docs/getting_started/quick_glance.rst
index 7189a0d13..f9a60c0eb 100644
--- a/docs/getting_started/quick_glance.rst
+++ b/docs/getting_started/quick_glance.rst
@@ -270,7 +270,7 @@ The only change in our view...point the renderer at the ``.jinja2`` file:
 Our Jinja2 template is very similar to our previous template:
 
 .. literalinclude:: quick_glance/jinja2/hello_world.jinja2
-    :language: html
+    :language: jinja
 
 Pyramid's templating add-ons register a new kind of renderer into your
 application. The renderer registration maps to different kinds of
@@ -432,9 +432,15 @@ Let's look at ``pserve`` and configuration in more depth.
 Application Running with ``pserve``
 ===================================
 
-When you install Pyramid, a small command program called ``pserve`` is
-written to your ``bin`` directory. This program is an executable Python
-module. It's very small, getting most of its brains via import.
+Prior to scaffolds, our project mixed a number of operations details
+into our code. Why should my main code care with HTTP server I want and
+what port number to run on?
+
+``pserve`` is Pyramid's application runner, separating operational
+details from your code. When you install Pyramid, a small command
+program called ``pserve`` is written to your ``bin`` directory. This
+program is an executable Python module. It's very small, getting most
+of its brains via import.
 
 You can run ``pserve`` with ``--help`` to see some of its options.
 Doing so reveals that you can ask ``pserve`` to watch your development
@@ -444,35 +450,22 @@ files and reload the server when they change:
 
     $ pserve development.ini --reload
 
-By design, ``pserve`` itself isn't all that interesting. Instead,
-its brains from your project's wiring, as expressed in the
-configuration file you supply it.
-
-.. seealso:: See Also: :ref:`what_is_this_pserve_thing`
-
-Three Cool Things About ``pserve``
-----------------------------------
-
-1. *Multiple .ini files*. You might have some settings in
-   development mode or some in production mode. Maybe you are writing an
-   add-on that needs to be wired-up by other people.
-
-2. *Choice of WSGI server*. ``pserve`` itself isn't a WSGI server.
-   Instead, it loads the server you want from the configuration file.
-
-3. *Friends of pserve*. With the ``pserve``/``.ini`` approach you
-   also get other commands that help during development: ``pshell``,
-   ``proutes``, ``pviews``, ``prequest``, etc.
+The ``pserve`` command has a number of other options and operations.
+Most of the work, though, comes from your project's wiring, as
+expressed in the configuration file you supply to ``pserve``. Let's
+take a look at this configuration file.
 
 Configuration with ``.ini`` Files
 =================================
 
 Earlier in *Quick Glance* we first met Pyramid's configuration system.
-At that point we did all configuration in Python code,
-aka *imperatively*. For example, the port number chosen for our HTTP
-server was right there in Python code. Our scaffold has moved this
-decision, and more, into *declarative* configuration in the
-``development.ini`` file.
+At that point we did all configuration in Python code. For example,
+the port number chosen for our HTTP server was right there in Python
+code. Our scaffold has moved this decision, and more, into the
+``development.ini`` file:
+
+.. literalinclude:: quick_glance/package/development.ini
+    :language: ini
 
 Let's take a quick high-level look. First, the ``.ini`` file is divided
 into sections:
@@ -485,7 +478,7 @@ into sections:
 
 - Various sections afterwards configure our Python logging system
 
-Let's look at a few decisions made in this configuration:
+We have a few decisions made for us in this configuration:
 
 #. *Choice of web server*. The ``use = egg:pyramid#wsgiref`` tell
    ``pserve`` to the ``wsgiref`` server that is wrapped in the Pyramid
@@ -520,9 +513,9 @@ illustrates several points about configuration.
 
 First, change your ``setup.py`` to say:
 
-.. code-block:: python
-
-    requires=['pyramid>=1.0.2', 'pyramid_jinja2']
+.. literalinclude:: quick_glance/package/setup.py
+    :start-after: Start Requires
+    :end-before: End Requires
 
 ...and re-run your setup:
 
@@ -530,26 +523,31 @@ First, change your ``setup.py`` to say:
 
     $ python ./setup.py develop
 
-The Python package was now installed into our environment but we
-haven't told our web app to use it. We can do so imperatively in code:
+The Python package was now installed into our environment. The package
+is a Pyramid add-on, which means we need to include its configuration
+into our web application. We could do this with imperative
+configuration, as we did above for the ``pyramid_jinja2`` add-on:
 
-.. code-block:: python
-
-  config.include('pyramid_debugtoolbar')
+.. literalinclude:: quick_glance/package/hello_world/__init__.py
+    :start-after: Start Include
+    :end-before: End Include
 
-Instead, let's do it in configuration by modifying our
+Now that we have a configuration file, we can use the
+``pyramid.includes`` facility and place this in our
 ``development.ini`` instead:
 
-.. code-block:: ini
-
-    [app:hello_world]
-    pyramid.includes = pyramid_debugtoolbar
+.. literalinclude:: quick_glance/package/development.ini
+    :language: ini
+    :start-after: Start Includes
+    :end-before: End Includes
 
-That is, add ``pyramid.includes = pyramid_debugtoolbar`` anywhere in the
-``[app:hello_world]`` section. You'll now see an attractive (and
-collapsible) menu in the right of your browser giving you introspective
+You'll now see an attractive (and
+collapsible) menu in the right of your browser, providing introspective
 access to debugging information. Even better, if your web application
-generates an error, you will see a nice traceback on the screen.
+generates an error, you will see a nice traceback on the screen. When
+you want to disable this toolbar, no need to change code: you can
+remove it from ``pyramid.includes`` in the relevant ``.ini``
+configuration file.
 
 Unit Tests and ``nose``
 =======================
@@ -577,7 +575,8 @@ We changed ``setup.py`` which means we need to re-run
 
 .. code-block:: bash
 
-    $ nosetests
+    $ cd hello_world
+    $ nosetests .
     .
     Name                  Stmts   Miss  Cover   Missing
     ---------------------------------------------------
@@ -594,25 +593,7 @@ We changed ``setup.py`` which means we need to re-run
 
 Our unit test passed. What did our test look like?
 
-.. code-block:: python
-
-    import unittest
-    from pyramid import testing
-
-
-    class ViewTests(unittest.TestCase):
-        def setUp(self):
-            testing.setUp()
-
-        def tearDown(self):
-            testing.tearDown()
-
-        def test_my_view(self):
-            from hello_world.views import my_view
-
-            request = testing.DummyRequest()
-            response = my_view(request)
-            self.assertEqual(response['project'], 'hello_world')
+.. literalinclude:: quick_glance/package/hello_world/tests.py
 
 Pyramid supplies helpers for test writing, which we use in the
 test setup and teardown. Our one test imports the view,
@@ -634,65 +615,75 @@ messages sent by Pyramid (for example, when a new request comes in.)
 Maybe you would like to log messages in your code? In your Python
 module, import and setup the logging:
 
-.. code-block:: python
-
-  import logging
-  log = logging.getLogger(__name__)
+.. literalinclude:: quick_glance/package/hello_world/views.py
+    :start-after: Start Logging 1
+    :end-before: End Logging 1
 
 You can now, in your code, log messages:
 
-.. code-block:: python
-
-    log.debug('Some Message')
+.. literalinclude:: quick_glance/package/hello_world/views.py
+    :start-after: Start Logging 2
+    :end-before: End Logging 2
 
 This will log ``Some Message`` at a ``debug`` log level,
 to the application-configured logger in your ``development.ini``. What
 controls that? These sections in the configuration file:
 
-.. code-block:: ini
-
-  [loggers]
-  keys = root, hello_world
-
-  [logger_hello_world]
-  level = DEBUG
-  handlers =
-  qualname = hello_world
+.. literalinclude:: quick_glance/package/development.ini
+    :language: ini
+    :start-after: Start Sphinx Include
+    :end-before: End Sphinx Include
 
 Our application, a package named ``hello_world``, is setup as a logger
-and configured to log messages at a ``DEBUG`` or higher level.
+and configured to log messages at a ``DEBUG`` or higher level. When you
+visit ``http://localhost:6543`` your console will now show::
+
+ 2013-08-09 10:42:42,968 DEBUG [hello_world.views][MainThread] Some Message
 
 Sessions
 ========
 
 When people use your web application, they frequently perform a task
-that requires semi-permanent data to be saved. For example,a shopping
-cart. These are frequently called *sessions*.
+that requires semi-permanent data to be saved. For example, a shopping
+cart. This is called a :term:`session`.
 
 Pyramid has basic built-in support for sessions, with add-ons such as
 *Beaker* (or your own custom sessioning engine) that provide richer
-session support. For the built-in session support, you first import
-the "factory" which provides the sessioning:
+session support. Let's take a look at the
+:doc:`built-in sessioning support <../narr/sessions>`. In our
+``__init__.py`` we first import the kind of sessioning we want:
 
-.. code-block:: python
+.. literalinclude:: quick_glance/package/hello_world/__init__.py
+    :start-after: Start Sphinx Include 1
+    :end-before: End Sphinx Include 1
 
-    from pyramid.session import UnencryptedCookieSessionFactoryConfig
-    my_session_factory = UnencryptedCookieSessionFactoryConfig('itsaseekreet')
+.. warning::
 
-We tell the configuration system that this is the source of our
-sessioning support when setting up the ``Configurator``:
+    As noted in the session docs, this example implementation is
+    not intended for use in settings with security implications.
 
-.. code-block:: python
+Now make a "factory" and pass it to the :term:`configurator`'s
+``session_factory`` argument:
 
-  config = Configurator(session_factory = my_session_factory)
+.. literalinclude:: quick_glance/package/hello_world/__init__.py
+    :start-after: Start Sphinx Include 2
+    :end-before: End Sphinx Include 2
 
-This now lets us use the session in our application code:
+Pyramid's :term:`request` object now has a ``session`` attribute
+that we can use in our view code:
 
-.. code-block:: python
+.. literalinclude:: quick_glance/package/hello_world/views.py
+    :start-after: Start Sphinx Include 1
+    :end-before: End Sphinx Include 1
+
+With this, each reload will increase the counter displayed in our
+Jinja2 template:
+
+.. literalinclude:: quick_glance/package/hello_world/templates/mytemplate.jinja2
+    :language: jinja
+    :start-after: Start Sphinx Include 1
+    :end-before: End Sphinx Include 1
 
-    session = request.session
-    if 'abc' in session:
-        session['fred'] = 'yes'
 
 Databases
 =========
@@ -708,8 +699,8 @@ scaffold!
 
 .. code-block:: bash
 
-  $ pcreate --scaffold alchemy hello_sqlalchemy
-  $ cd hello_sqlalchemy
+  $ pcreate --scaffold alchemy sqla_demo
+  $ cd sqla_demo
   $ python setup.py develop
 
 We now have a working sample SQLAlchemy application with all
@@ -719,80 +710,97 @@ the application:
 
 .. code-block:: bash
 
-  $ initialize_hello_sqlalchemy_db development.ini
+  $ initialize_sqla_demo_db development.ini
   $ pserve development.ini
 
-We can now visit our sample at
-`http://localhost:6543/ <http://localhost:6543/>`_. Some choices that
-the scaffold helped us with:
-
-- A ``setup.py`` with appropriate dependencies
+The ORM eases the mapping of database structures into a programming
+language. SQLAlchemy uses "models" for this mapping. The scaffold
+generated a sample model:
 
-- Connection strings and integration in our ``development.ini`` file
+.. literalinclude:: quick_glance/sqla_demo/sqla_demo/models.py
+    :start-after: Start Sphinx Include
+    :end-before: End Sphinx Include
 
-- A console script which we ran above to initialize the database
+View code, which mediates the logic between web requests and the rest
+of the system, can then easily get at the data thanks to SQLAlchemy:
 
-- The SQLAlchemy engine integrated into the ``Configurator`` on
-  application startup
+.. literalinclude:: quick_glance/sqla_demo/sqla_demo/views.py
+    :start-after: Start Sphinx Include
+    :end-before: End Sphinx Include
 
-- Python modules for the SQLAlchemy models and the Pyramid views that
-  go with them
+Forms
+=====
 
-- Some unit tests...yummy!
+Developers have lots of opinions about web forms, and thus there are many
+form libraries for Python. Pyramid doesn't directly bundle a form
+library, but *Deform* is a popular choice for forms,
+along with its related *Colander* schema system.
 
-As mentioned above, an ORM is software that eases the mapping of
-database structures into a programming language. SQLAlchemy uses models
-for this, and its scaffold generated a sample model:
+As an example, imagine we want a form that edits a wiki page. The form
+should have two fields on it, one of them a required title and the
+other a rich text editor for the body. With Deform we can express this
+as a Colander schema:
 
 .. code-block:: python
 
-    class MyModel(Base):
-        __tablename__ = 'models'
-        id = Column(Integer, primary_key=True)
-        name = Column(Text, unique=True)
-        value = Column(Integer)
+    class WikiPage(colander.MappingSchema):
+        title = colander.SchemaNode(colander.String())
+        body = colander.SchemaNode(
+            colander.String(),
+            widget=deform.widget.RichTextWidget()
+        )
 
-        def __init__(self, name, value):
-            self.name = name
-            self.value = value
-
-The Python module also includes this:
+With this in place, we can render the HTML for a form,
+perhaps with form data from an existing page:
 
 .. code-block:: python
 
-  from zope.sqlalchemy import ZopeTransactionExtension
-
-The generated application includes the optional support for
-``pyramid_tm``, a unique transaction monitor that integrates your
-database transactions with your code for transparent rollback and commit.
+    form = self.wiki_form.render()
 
-View code, which mediates the logic between web requests and the rest
-of the system, can then easily get at the data:
+We'd like to handle form submission, validation, and saving:
 
 .. code-block:: python
 
-  one = DBSession.query(MyModel).filter(MyModel.name == 'one').first()
-
-
-Forms
-=====
+    # Get the form data that was posted
+    controls = self.request.POST.items()
+    try:
+        # Validate and either raise a validation error
+        # or return deserialized data from widgets
+        appstruct = wiki_form.validate(controls)
+    except deform.ValidationFailure as e:
+        # Bail out and render form with errors
+        return dict(title=title, page=page, form=e.render())
 
-Developers have lots of opinions about forms, and thus there are many
-form libraries for Python. Pyramid doesn't directly bundle a form
-library, but *Deform* is a popular choice. Let's see it in action.
-First we install it:
+    # Change the content and redirect to the view
+    page['title'] = appstruct['title']
+    page['body'] = appstruct['body']
 
-.. code-block:: bash
+Deform and Colander provide a very flexible combination for forms,
+widgets, schemas, and validation. Recent versions of Deform also
+include a
+`retail mode <http://docs.pylonsproject
+.org/projects/deform/en/latest/retail.html>`_
+for gaining Deform
+features on custom forms.
 
-  $ pip-3.3 install deform
+Also, the ``deform_bootstrap`` Pyramid add-on restyles the stock Deform
+widgets using attractive CSS from Bootstrap and more powerful widgets
+from Chosen.
 
+Awesome Pyramid Features
+========================
 
+For the most part this *Quick Glance* has covered concepts that are
+common in Python web frameworks. Pyramid has a unique niche,
+though. It helps you start with a small project that grows into a
+larger project. Let's look at some of the unique facilities that help.
 
-Authentication
-==============
 
 
-Authorization
-=============
 
+Conclusion
+==========
 
+This *Quick Glance* was a little about a lot. We introduced a long list
+of concepts in Pyramid, many of which are expanded on more fully later
+in *Getting Started* and certainly in the Pyramid developer docs.
\ No newline at end of file
diff --git a/docs/getting_started/quick_glance/hello_sqlalchemy/MANIFEST.in b/docs/getting_started/quick_glance/hello_sqlalchemy/MANIFEST.in
deleted file mode 100644
index 2a06ba607..000000000
--- a/docs/getting_started/quick_glance/hello_sqlalchemy/MANIFEST.in
+++ /dev/null
@@ -1,2 +0,0 @@
-include *.txt *.ini *.cfg *.rst
-recursive-include hello_sqlalchemy *.ico *.png *.css *.gif *.jpg *.pt *.txt *.mak *.mako *.js *.html *.xml
diff --git a/docs/getting_started/quick_glance/hello_sqlalchemy/setup.cfg b/docs/getting_started/quick_glance/hello_sqlalchemy/setup.cfg
deleted file mode 100644
index d08bf9c9b..000000000
--- a/docs/getting_started/quick_glance/hello_sqlalchemy/setup.cfg
+++ /dev/null
@@ -1,27 +0,0 @@
-[nosetests]
-match=^test
-nocapture=1
-cover-package=hello_sqlalchemy
-with-coverage=1
-cover-erase=1
-
-[compile_catalog]
-directory = hello_sqlalchemy/locale
-domain = hello_sqlalchemy
-statistics = true
-
-[extract_messages]
-add_comments = TRANSLATORS:
-output_file = hello_sqlalchemy/locale/hello_sqlalchemy.pot
-width = 80
-
-[init_catalog]
-domain = hello_sqlalchemy
-input_file = hello_sqlalchemy/locale/hello_sqlalchemy.pot
-output_dir = hello_sqlalchemy/locale
-
-[update_catalog]
-domain = hello_sqlalchemy
-input_file = hello_sqlalchemy/locale/hello_sqlalchemy.pot
-output_dir = hello_sqlalchemy/locale
-previous = true
diff --git a/docs/getting_started/quick_glance/package/development.ini b/docs/getting_started/quick_glance/package/development.ini
index 9aa5f40cf..a751ff903 100644
--- a/docs/getting_started/quick_glance/package/development.ini
+++ b/docs/getting_started/quick_glance/package/development.ini
@@ -1,5 +1,7 @@
+# Start Includes
 [app:hello_world]
 pyramid.includes = pyramid_debugtoolbar
+# End Includes
 use = egg:hello_world
 reload_templates = true
 debug_authorization = false
@@ -22,9 +24,16 @@ port = 6543
 
 # Begin logging configuration
 
+# Start Sphinx Include
 [loggers]
 keys = root, hello_world
 
+[logger_hello_world]
+level = DEBUG
+handlers =
+qualname = hello_world
+# End Sphinx Include
+
 [handlers]
 keys = console
 
@@ -35,10 +44,6 @@ keys = generic
 level = INFO
 handlers = console
 
-[logger_hello_world]
-level = DEBUG
-handlers =
-qualname = hello_world
 
 [handler_console]
 class = StreamHandler
diff --git a/docs/getting_started/quick_glance/package/hello_world/__init__.py b/docs/getting_started/quick_glance/package/hello_world/__init__.py
index 9b5753c26..6e66bf40a 100644
--- a/docs/getting_started/quick_glance/package/hello_world/__init__.py
+++ b/docs/getting_started/quick_glance/package/hello_world/__init__.py
@@ -1,5 +1,9 @@
 from pyramid.config import Configurator
 from pyramid_jinja2 import renderer_factory
+# Start Sphinx Include 1
+from pyramid.session import UnencryptedCookieSessionFactoryConfig
+# End Sphinx Include 1
+
 from hello_world.models import get_root
 
 def main(global_config, **settings):
@@ -11,9 +15,16 @@ def main(global_config, **settings):
     settings = dict(settings)
     settings.setdefault('jinja2.i18n.domain', 'hello_world')
 
-    config = Configurator(root_factory=get_root, settings=settings)
+    # Start Sphinx Include 2
+    my_session_factory = UnencryptedCookieSessionFactoryConfig('itsaseekreet')
+    config = Configurator(root_factory=get_root, settings=settings,
+                          session_factory=my_session_factory)
+    # End Sphinx Include 2
     config.add_translation_dirs('locale/')
+    # Start Include
     config.include('pyramid_jinja2')
+    # End Include
+
 
     config.add_static_view('static', 'static')
     config.add_view('hello_world.views.my_view',
diff --git a/docs/getting_started/quick_glance/package/hello_world/templates/mytemplate.jinja2 b/docs/getting_started/quick_glance/package/hello_world/templates/mytemplate.jinja2
index 998edfe12..25a28ed7a 100644
--- a/docs/getting_started/quick_glance/package/hello_world/templates/mytemplate.jinja2
+++ b/docs/getting_started/quick_glance/package/hello_world/templates/mytemplate.jinja2
@@ -35,7 +35,10 @@
 		<div id="bottom">
           <div class="locale">
             <h2>{% trans %}Hello!{% endtrans %}</h2>
-            <p>Request performed with <span class="locale-name">{{ request.locale_name }}</span> locale.</p> 
+          <!-- Start Sphinx Include 1 -->
+          <p>Counter: {{ request.session.counter }}</p>
+          <!-- End Sphinx Include 1 -->
+            <p>Request performed with <span class="locale-name">{{ request.locale_name }}</span> locale.</p>
           </div>
 			<div class="bottom">
 				<div id="left" class="align-right">
diff --git a/docs/getting_started/quick_glance/package/hello_world/tests.py b/docs/getting_started/quick_glance/package/hello_world/tests.py
index a81c29eb0..ccec14f70 100644
--- a/docs/getting_started/quick_glance/package/hello_world/tests.py
+++ b/docs/getting_started/quick_glance/package/hello_world/tests.py
@@ -18,4 +18,3 @@ class ViewTests(unittest.TestCase):
         request = testing.DummyRequest()
         response = my_view(request)
         self.assertEqual(response['project'], 'hello_world')
-
diff --git a/docs/getting_started/quick_glance/package/hello_world/views.py b/docs/getting_started/quick_glance/package/hello_world/views.py
index c271d45dd..109c260ad 100644
--- a/docs/getting_started/quick_glance/package/hello_world/views.py
+++ b/docs/getting_started/quick_glance/package/hello_world/views.py
@@ -1,6 +1,22 @@
+# Start Logging 1
+import logging
+log = logging.getLogger(__name__)
+# End Logging 1
+
 from pyramid.i18n import TranslationStringFactory
 
 _ = TranslationStringFactory('hello_world')
 
+
 def my_view(request):
-    return {'project':'hello_world'}
+    # Start Logging 2
+    log.debug('Some Message')
+    # End Logging 2
+    # Start Sphinx Include 1
+    session = request.session
+    if 'counter' in session:
+        session['counter'] += 1
+    else:
+        session['counter'] = 0
+    # End Sphinx Include 1
+    return {'project': 'hello_world'}
diff --git a/docs/getting_started/quick_glance/package/setup.py b/docs/getting_started/quick_glance/package/setup.py
index 6269accf1..f118ed5fb 100644
--- a/docs/getting_started/quick_glance/package/setup.py
+++ b/docs/getting_started/quick_glance/package/setup.py
@@ -6,7 +6,9 @@ here = os.path.abspath(os.path.dirname(__file__))
 README = open(os.path.join(here, 'README.txt')).read()
 CHANGES = open(os.path.join(here, 'CHANGES.txt')).read()
 
+# Start Requires
 requires = ['pyramid>=1.0.2', 'pyramid_jinja2', 'pyramid_debugtoolbar']
+# End Requires
 
 setup(name='hello_world',
       version='0.0',
diff --git a/docs/getting_started/quick_glance/hello_sqlalchemy/CHANGES.txt b/docs/getting_started/quick_glance/sqla_demo/CHANGES.txt
index 35a34f332..35a34f332 100644
--- a/docs/getting_started/quick_glance/hello_sqlalchemy/CHANGES.txt
+++ b/docs/getting_started/quick_glance/sqla_demo/CHANGES.txt
diff --git a/docs/getting_started/quick_glance/sqla_demo/MANIFEST.in b/docs/getting_started/quick_glance/sqla_demo/MANIFEST.in
new file mode 100644
index 000000000..a432577e9
--- /dev/null
+++ b/docs/getting_started/quick_glance/sqla_demo/MANIFEST.in
@@ -0,0 +1,2 @@
+include *.txt *.ini *.cfg *.rst
+recursive-include sqla_demo *.ico *.png *.css *.gif *.jpg *.pt *.txt *.mak *.mako *.js *.html *.xml
diff --git a/docs/getting_started/quick_glance/hello_sqlalchemy/README.txt b/docs/getting_started/quick_glance/sqla_demo/README.txt
index b7a6612a0..f35d3aec5 100644
--- a/docs/getting_started/quick_glance/hello_sqlalchemy/README.txt
+++ b/docs/getting_started/quick_glance/sqla_demo/README.txt
@@ -1,4 +1,4 @@
-hello_sqlalchemy README
+sqla_demo README
 ==================
 
 Getting Started
@@ -8,7 +8,7 @@ Getting Started
 
 - $venv/bin/python setup.py develop
 
-- $venv/bin/initialize_hello_sqlalchemy_db development.ini
+- $venv/bin/initialize_sqla_demo_db development.ini
 
 - $venv/bin/pserve development.ini
 
diff --git a/docs/getting_started/quick_glance/hello_sqlalchemy/development.ini b/docs/getting_started/quick_glance/sqla_demo/development.ini
index 59ae96568..174468abf 100644
--- a/docs/getting_started/quick_glance/hello_sqlalchemy/development.ini
+++ b/docs/getting_started/quick_glance/sqla_demo/development.ini
@@ -4,7 +4,7 @@
 ###
 
 [app:main]
-use = egg:hello_sqlalchemy
+use = egg:sqla_demo
 
 pyramid.reload_templates = true
 pyramid.debug_authorization = false
@@ -15,7 +15,7 @@ pyramid.includes =
     pyramid_debugtoolbar
     pyramid_tm
 
-sqlalchemy.url = sqlite:///%(here)s/hello_sqlalchemy.sqlite
+sqlalchemy.url = sqlite:///%(here)s/sqla_demo.sqlite
 
 # By default, the toolbar only appears for clients from IP addresses
 # '127.0.0.1' and '::1'.
@@ -36,7 +36,7 @@ port = 6543
 ###
 
 [loggers]
-keys = root, hello_sqlalchemy, sqlalchemy
+keys = root, sqla_demo, sqlalchemy
 
 [handlers]
 keys = console
@@ -48,10 +48,10 @@ keys = generic
 level = INFO
 handlers = console
 
-[logger_hello_sqlalchemy]
+[logger_sqla_demo]
 level = DEBUG
 handlers =
-qualname = hello_sqlalchemy
+qualname = sqla_demo
 
 [logger_sqlalchemy]
 level = INFO
diff --git a/docs/getting_started/quick_glance/hello_sqlalchemy/production.ini b/docs/getting_started/quick_glance/sqla_demo/production.ini
index 3257d0067..dc0ba304f 100644
--- a/docs/getting_started/quick_glance/hello_sqlalchemy/production.ini
+++ b/docs/getting_started/quick_glance/sqla_demo/production.ini
@@ -4,7 +4,7 @@
 ###
 
 [app:main]
-use = egg:hello_sqlalchemy
+use = egg:sqla_demo
 
 pyramid.reload_templates = false
 pyramid.debug_authorization = false
@@ -14,7 +14,7 @@ pyramid.default_locale_name = en
 pyramid.includes =
     pyramid_tm
 
-sqlalchemy.url = sqlite:///%(here)s/hello_sqlalchemy.sqlite
+sqlalchemy.url = sqlite:///%(here)s/sqla_demo.sqlite
 
 [server:main]
 use = egg:waitress#main
@@ -27,7 +27,7 @@ port = 6543
 ###
 
 [loggers]
-keys = root, hello_sqlalchemy, sqlalchemy
+keys = root, sqla_demo, sqlalchemy
 
 [handlers]
 keys = console
@@ -39,10 +39,10 @@ keys = generic
 level = WARN
 handlers = console
 
-[logger_hello_sqlalchemy]
+[logger_sqla_demo]
 level = WARN
 handlers =
-qualname = hello_sqlalchemy
+qualname = sqla_demo
 
 [logger_sqlalchemy]
 level = WARN
diff --git a/docs/getting_started/quick_glance/sqla_demo/setup.cfg b/docs/getting_started/quick_glance/sqla_demo/setup.cfg
new file mode 100644
index 000000000..9f91cd122
--- /dev/null
+++ b/docs/getting_started/quick_glance/sqla_demo/setup.cfg
@@ -0,0 +1,27 @@
+[nosetests]
+match=^test
+nocapture=1
+cover-package=sqla_demo
+with-coverage=1
+cover-erase=1
+
+[compile_catalog]
+directory = sqla_demo/locale
+domain = sqla_demo
+statistics = true
+
+[extract_messages]
+add_comments = TRANSLATORS:
+output_file = sqla_demo/locale/sqla_demo.pot
+width = 80
+
+[init_catalog]
+domain = sqla_demo
+input_file = sqla_demo/locale/sqla_demo.pot
+output_dir = sqla_demo/locale
+
+[update_catalog]
+domain = sqla_demo
+input_file = sqla_demo/locale/sqla_demo.pot
+output_dir = sqla_demo/locale
+previous = true
diff --git a/docs/getting_started/quick_glance/hello_sqlalchemy/setup.py b/docs/getting_started/quick_glance/sqla_demo/setup.py
index f4e1f48c0..ac2eed035 100644
--- a/docs/getting_started/quick_glance/hello_sqlalchemy/setup.py
+++ b/docs/getting_started/quick_glance/sqla_demo/setup.py
@@ -16,9 +16,9 @@ requires = [
     'waitress',
     ]
 
-setup(name='hello_sqlalchemy',
+setup(name='sqla_demo',
       version='0.0',
-      description='hello_sqlalchemy',
+      description='sqla_demo',
       long_description=README + '\n\n' + CHANGES,
       classifiers=[
         "Programming Language :: Python",
@@ -33,12 +33,12 @@ setup(name='hello_sqlalchemy',
       packages=find_packages(),
       include_package_data=True,
       zip_safe=False,
-      test_suite='hello_sqlalchemy',
+      test_suite='sqla_demo',
       install_requires=requires,
       entry_points="""\
       [paste.app_factory]
-      main = hello_sqlalchemy:main
+      main = sqla_demo:main
       [console_scripts]
-      initialize_hello_sqlalchemy_db = hello_sqlalchemy.scripts.initializedb:main
+      initialize_sqla_demo_db = sqla_demo.scripts.initializedb:main
       """,
       )
diff --git a/docs/getting_started/quick_glance/hello_sqlalchemy/hello_sqlalchemy.sqlite b/docs/getting_started/quick_glance/sqla_demo/sqla_demo.sqlite
index fa6adb104..fa6adb104 100644
--- a/docs/getting_started/quick_glance/hello_sqlalchemy/hello_sqlalchemy.sqlite
+++ b/docs/getting_started/quick_glance/sqla_demo/sqla_demo.sqlite
diff --git a/docs/getting_started/quick_glance/hello_sqlalchemy/hello_sqlalchemy/__init__.py b/docs/getting_started/quick_glance/sqla_demo/sqla_demo/__init__.py
index aac7c5e69..aac7c5e69 100644
--- a/docs/getting_started/quick_glance/hello_sqlalchemy/hello_sqlalchemy/__init__.py
+++ b/docs/getting_started/quick_glance/sqla_demo/sqla_demo/__init__.py
diff --git a/docs/getting_started/quick_glance/hello_sqlalchemy/hello_sqlalchemy/models.py b/docs/getting_started/quick_glance/sqla_demo/sqla_demo/models.py
index aeeb9df64..3dfb40e58 100644
--- a/docs/getting_started/quick_glance/hello_sqlalchemy/hello_sqlalchemy/models.py
+++ b/docs/getting_started/quick_glance/sqla_demo/sqla_demo/models.py
@@ -16,7 +16,7 @@ from zope.sqlalchemy import ZopeTransactionExtension
 DBSession = scoped_session(sessionmaker(extension=ZopeTransactionExtension()))
 Base = declarative_base()
 
-
+# Start Sphinx Include
 class MyModel(Base):
     __tablename__ = 'models'
     id = Column(Integer, primary_key=True)
@@ -26,3 +26,4 @@ class MyModel(Base):
     def __init__(self, name, value):
         self.name = name
         self.value = value
+    # End Sphinx Include
diff --git a/docs/getting_started/quick_glance/hello_sqlalchemy/hello_sqlalchemy/scripts/__init__.py b/docs/getting_started/quick_glance/sqla_demo/sqla_demo/scripts/__init__.py
index 5bb534f79..5bb534f79 100644
--- a/docs/getting_started/quick_glance/hello_sqlalchemy/hello_sqlalchemy/scripts/__init__.py
+++ b/docs/getting_started/quick_glance/sqla_demo/sqla_demo/scripts/__init__.py
diff --git a/docs/getting_started/quick_glance/hello_sqlalchemy/hello_sqlalchemy/scripts/initializedb.py b/docs/getting_started/quick_glance/sqla_demo/sqla_demo/scripts/initializedb.py
index 66feb3008..66feb3008 100644
--- a/docs/getting_started/quick_glance/hello_sqlalchemy/hello_sqlalchemy/scripts/initializedb.py
+++ b/docs/getting_started/quick_glance/sqla_demo/sqla_demo/scripts/initializedb.py
diff --git a/docs/getting_started/quick_glance/hello_sqlalchemy/hello_sqlalchemy/static/favicon.ico b/docs/getting_started/quick_glance/sqla_demo/sqla_demo/static/favicon.ico
index 71f837c9e..71f837c9e 100644
--- a/docs/getting_started/quick_glance/hello_sqlalchemy/hello_sqlalchemy/static/favicon.ico
+++ b/docs/getting_started/quick_glance/sqla_demo/sqla_demo/static/favicon.ico
diff --git a/docs/getting_started/quick_glance/hello_sqlalchemy/hello_sqlalchemy/static/footerbg.png b/docs/getting_started/quick_glance/sqla_demo/sqla_demo/static/footerbg.png
index 1fbc873da..1fbc873da 100644
--- a/docs/getting_started/quick_glance/hello_sqlalchemy/hello_sqlalchemy/static/footerbg.png
+++ b/docs/getting_started/quick_glance/sqla_demo/sqla_demo/static/footerbg.png
diff --git a/docs/getting_started/quick_glance/hello_sqlalchemy/hello_sqlalchemy/static/headerbg.png b/docs/getting_started/quick_glance/sqla_demo/sqla_demo/static/headerbg.png
index 0596f2020..0596f2020 100644
--- a/docs/getting_started/quick_glance/hello_sqlalchemy/hello_sqlalchemy/static/headerbg.png
+++ b/docs/getting_started/quick_glance/sqla_demo/sqla_demo/static/headerbg.png
diff --git a/docs/getting_started/quick_glance/hello_sqlalchemy/hello_sqlalchemy/static/ie6.css b/docs/getting_started/quick_glance/sqla_demo/sqla_demo/static/ie6.css
index b7c8493d8..b7c8493d8 100644
--- a/docs/getting_started/quick_glance/hello_sqlalchemy/hello_sqlalchemy/static/ie6.css
+++ b/docs/getting_started/quick_glance/sqla_demo/sqla_demo/static/ie6.css
diff --git a/docs/getting_started/quick_glance/hello_sqlalchemy/hello_sqlalchemy/static/middlebg.png b/docs/getting_started/quick_glance/sqla_demo/sqla_demo/static/middlebg.png
index 2369cfb7d..2369cfb7d 100644
--- a/docs/getting_started/quick_glance/hello_sqlalchemy/hello_sqlalchemy/static/middlebg.png
+++ b/docs/getting_started/quick_glance/sqla_demo/sqla_demo/static/middlebg.png
diff --git a/docs/getting_started/quick_glance/hello_sqlalchemy/hello_sqlalchemy/static/pylons.css b/docs/getting_started/quick_glance/sqla_demo/sqla_demo/static/pylons.css
index 4b1c017cd..4b1c017cd 100644
--- a/docs/getting_started/quick_glance/hello_sqlalchemy/hello_sqlalchemy/static/pylons.css
+++ b/docs/getting_started/quick_glance/sqla_demo/sqla_demo/static/pylons.css
diff --git a/docs/getting_started/quick_glance/hello_sqlalchemy/hello_sqlalchemy/static/pyramid-small.png b/docs/getting_started/quick_glance/sqla_demo/sqla_demo/static/pyramid-small.png
index a5bc0ade7..a5bc0ade7 100644
--- a/docs/getting_started/quick_glance/hello_sqlalchemy/hello_sqlalchemy/static/pyramid-small.png
+++ b/docs/getting_started/quick_glance/sqla_demo/sqla_demo/static/pyramid-small.png
diff --git a/docs/getting_started/quick_glance/hello_sqlalchemy/hello_sqlalchemy/static/pyramid.png b/docs/getting_started/quick_glance/sqla_demo/sqla_demo/static/pyramid.png
index 347e05549..347e05549 100644
--- a/docs/getting_started/quick_glance/hello_sqlalchemy/hello_sqlalchemy/static/pyramid.png
+++ b/docs/getting_started/quick_glance/sqla_demo/sqla_demo/static/pyramid.png
diff --git a/docs/getting_started/quick_glance/hello_sqlalchemy/hello_sqlalchemy/static/transparent.gif b/docs/getting_started/quick_glance/sqla_demo/sqla_demo/static/transparent.gif
index 0341802e5..0341802e5 100644
--- a/docs/getting_started/quick_glance/hello_sqlalchemy/hello_sqlalchemy/static/transparent.gif
+++ b/docs/getting_started/quick_glance/sqla_demo/sqla_demo/static/transparent.gif
diff --git a/docs/getting_started/quick_glance/hello_sqlalchemy/hello_sqlalchemy/templates/mytemplate.pt b/docs/getting_started/quick_glance/sqla_demo/sqla_demo/templates/mytemplate.pt
index 2de66d4c9..e0ac9d440 100644
--- a/docs/getting_started/quick_glance/hello_sqlalchemy/hello_sqlalchemy/templates/mytemplate.pt
+++ b/docs/getting_started/quick_glance/sqla_demo/sqla_demo/templates/mytemplate.pt
@@ -1,30 +1,30 @@
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" xmlns:tal="http://xml.zope.org/namespaces/tal">
 <head>
-  <title>The Pyramid Web Framework</title>
+  <title>The Pyramid Web Application Development Framework</title>
   <meta http-equiv="Content-Type" content="text/html;charset=UTF-8"/>
   <meta name="keywords" content="python web application" />
   <meta name="description" content="pyramid web application" />
-  <link rel="shortcut icon" href="${request.static_url('hello_sqlalchemy:static/favicon.ico')}" />
-  <link rel="stylesheet" href="${request.static_url('hello_sqlalchemy:static/pylons.css')}" type="text/css" media="screen" charset="utf-8" />
+  <link rel="shortcut icon" href="${request.static_url('sqla_demo:static/favicon.ico')}" />
+  <link rel="stylesheet" href="${request.static_url('sqla_demo:static/pylons.css')}" type="text/css" media="screen" charset="utf-8" />
   <link rel="stylesheet" href="http://static.pylonsproject.org/fonts/nobile/stylesheet.css" media="screen" />
   <link rel="stylesheet" href="http://static.pylonsproject.org/fonts/neuton/stylesheet.css" media="screen" />
   <!--[if lte IE 6]>
-  <link rel="stylesheet" href="${request.static_url('hello_sqlalchemy:static/ie6.css')}" type="text/css" media="screen" charset="utf-8" />
+  <link rel="stylesheet" href="${request.static_url('sqla_demo:static/ie6.css')}" type="text/css" media="screen" charset="utf-8" />
   <![endif]-->
 </head>
 <body>
   <div id="wrap">
     <div id="top">
       <div class="top align-center">
-        <div><img src="${request.static_url('hello_sqlalchemy:static/pyramid.png')}" width="750" height="169" alt="pyramid"/></div>
+        <div><img src="${request.static_url('sqla_demo:static/pyramid.png')}" width="750" height="169" alt="pyramid"/></div>
       </div>
     </div>
     <div id="middle">
       <div class="middle align-center">
         <p class="app-welcome">
           Welcome to <span class="app-name">${project}</span>, an application generated by<br/>
-          the Pyramid Web Framework.
+          the Pyramid web application development framework.
         </p>
       </div>
     </div>
diff --git a/docs/getting_started/quick_glance/hello_sqlalchemy/hello_sqlalchemy/tests.py b/docs/getting_started/quick_glance/sqla_demo/sqla_demo/tests.py
index e2789665b..6fef6d695 100644
--- a/docs/getting_started/quick_glance/hello_sqlalchemy/hello_sqlalchemy/tests.py
+++ b/docs/getting_started/quick_glance/sqla_demo/sqla_demo/tests.py
@@ -30,4 +30,4 @@ class TestMyView(unittest.TestCase):
         request = testing.DummyRequest()
         info = my_view(request)
         self.assertEqual(info['one'].name, 'one')
-        self.assertEqual(info['project'], 'hello_sqlalchemy')
+        self.assertEqual(info['project'], 'sqla_demo')
diff --git a/docs/getting_started/quick_glance/hello_sqlalchemy/hello_sqlalchemy/views.py b/docs/getting_started/quick_glance/sqla_demo/sqla_demo/views.py
index 796acf738..768a7e42e 100644
--- a/docs/getting_started/quick_glance/hello_sqlalchemy/hello_sqlalchemy/views.py
+++ b/docs/getting_started/quick_glance/sqla_demo/sqla_demo/views.py
@@ -1,9 +1,6 @@
 from pyramid.response import Response
 from pyramid.view import view_config
 
-import colander
-import deform
-
 from sqlalchemy.exc import DBAPIError
 
 from .models import (
@@ -11,26 +8,22 @@ from .models import (
     MyModel,
     )
 
-class MyForm(colander.MappingSchema):
-    title = colander.SchemaNode(colander.String())
-    body = colander.SchemaNode(
-        colander.String(),
-        widget=deform.widget.RichTextWidget()
-    )
 
 @view_config(route_name='home', renderer='templates/mytemplate.pt')
 def my_view(request):
     try:
+        # Start Sphinx Include
         one = DBSession.query(MyModel).filter(MyModel.name == 'one').first()
+        # End Sphinx Include
     except DBAPIError:
         return Response(conn_err_msg, content_type='text/plain', status_int=500)
-    return {'one': one, 'project': 'hello_sqlalchemy'}
+    return {'one': one, 'project': 'sqla_demo'}
 
 conn_err_msg = """\
 Pyramid is having a problem using your SQL database.  The problem
 might be caused by one of the following things:
 
-1.  You may need to run the "initialize_hello_sqlalchemy_db" script
+1.  You may need to run the "initialize_sqla_demo_db" script
     to initialize your database tables.  Check your virtual 
     environment's "bin" directory for this script and try to run it.
 
diff --git a/docs/getting_started/top_ten.rst b/docs/getting_started/top_ten.rst
index a11d2898c..e207f4ce1 100644
--- a/docs/getting_started/top_ten.rst
+++ b/docs/getting_started/top_ten.rst
@@ -2,31 +2,40 @@
 Top Killer Features In Pyramid
 ==============================
 
-"Making your own framework"
-
-- Transactions
+As a regular developer
 
 - Configuration
 
-  - config.include
+- Route factories and contexts
 
-- Advanced views and view predicates
+- Advanced view configuration
 
-Custom views
-============
+- Route prefixes
 
-- Corneice does this
+- Asset specifications
 
 - Events
 
-- Ordered routes
-
 - Custom renderers
 
 - Tweens
 
-- Asset specifications
+- Transactions
 
 - Traversal
 
-- Transactions
\ No newline at end of file
+- Custom directives
+
+- config.include
+
+- Extensible applications
+
+  - Overridable views, routes, and assets
+
+  - config.include
+
+  - Events
+
+  - Distributing an add-on
+
+  - "Making your own framework", Extensibility
diff --git a/docs/getting_started/views.rst b/docs/getting_started/views.rst
index 827778a66..f30caea8a 100644
--- a/docs/getting_started/views.rst
+++ b/docs/getting_started/views.rst
@@ -17,22 +17,12 @@ person, then editing that person or perhaps deleting that person. They
 might logically belong together. We could do these as independent
 functions, but let's do them together as a view class:
 
-.. literalinclude:: quick_glance/view_classes/views.py
-    :start-after: Start View 1
-    :end-before: End View 1
 
 ...and some routes that wire up the views to URLs:
 
-.. literalinclude:: quick_glance/view_classes/app.py
-    :start-after: Start Routes 1
-    :end-before: End Routes 1
 
 ...and a form in ``hello_world.jinja2`` that submits to the second view:
 
-.. literalinclude:: quick_glance/view_classes/hello_world.jinja2
-    :language: html
-    :start-after: Start Form 1
-    :end-before: End Form 1
 
 Just to review: