Merge pull request #1123 from tshepang/docs.quicktutorial

Paul Everitt

2013-09-16 4524d905975b481aee7f84b079a3abc5036508a6

Merge pull request #1123 from tshepang/docs.quicktutorial

s/env/venv + make example links clickable

 docs/quick_tour.rst

@@ -25,9 +25,9 @@

.. code-block:: bash

  $ pyvenv-3.3 env33
  $ source env33/bin/activate
  $ wget https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py -O - | python
  $ pyvenv-3.3 venv
  $ source venv/bin/activate
  (venv)$ wget https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py -O - | python

If ``wget`` complains with a certificate error, run it with:

@@ -37,7 +37,7 @@

In these steps above we first made a :term:`virtualenv` and then
"activated"  it, which adjusted our path to look first in
``env33/bin`` for commands (such as ``python``). We next downloaded
``venv/bin`` for commands (such as ``python``). We next downloaded
Python's packaging support and installed it, giving us the
``easy_install`` command-line script for adding new packages. Python
2.7 users will need to use ``virtualenv`` instead of ``pyvenv`` to make

 docs/quick_tutorial/authentication.rst

@@ -32,8 +32,8 @@

   .. code-block:: bash

    (env)$ cd ..; cp -r view_classes authentication; cd authentication
    (env)$ python setup.py develop
    (venv)$ cd ..; cp -r view_classes authentication; cd authentication
    (venv)$ python setup.py develop

#. Put the security hash in the ``authentication/development.ini``
   configuration file as ``tutorial.secret`` instead of putting it in
@@ -77,9 +77,9 @@

   .. code-block:: bash

    (env)$ pserve development.ini --reload
    (venv)$ pserve development.ini --reload

#. Open ``http://localhost:6543/`` in a browser.
#. Open http://localhost:6543/ in a browser.

#. Click the "Log In" link.


 docs/quick_tutorial/authorization.rst

@@ -37,8 +37,8 @@

   .. code-block:: bash

    (env)$ cd ..; cp -r authentication authorization; cd authorization
    (env)$ python setup.py develop
    (venv)$ cd ..; cp -r authentication authorization; cd authorization
    (venv)$ python setup.py develop

#. Start by changing ``authorization/tutorial/__init__.py`` to
   specify a root factory to the :term:`configurator`:
@@ -62,13 +62,13 @@

   .. code-block:: bash

    (env)$ pserve development.ini --reload
    (venv)$ pserve development.ini --reload

#. Open ``http://localhost:6543/`` in a browser.
#. Open http://localhost:6543/ in a browser.

#. If you are still logged in, click the "Log Out" link.

#. Visit ``http://localhost:6543/howdy`` in a browser. You should be
#. Visit http://localhost:6543/howdy in a browser. You should be
   asked to login.

Analysis

 docs/quick_tutorial/databases.rst

@@ -41,7 +41,7 @@

   .. code-block:: bash

    (env)$ cd ..; cp -r forms databases; cd databases
    (venv)$ cd ..; cp -r forms databases; cd databases

#. We need to add some dependencies in ``databases/setup.py`` as well
   as an "entry point" for the command-line script:
@@ -75,7 +75,7 @@

   .. code-block:: bash

    (env)$ python setup.py develop
    (venv)$ python setup.py develop

#. The script references some models in ``databases/tutorial/models.py``:

@@ -86,7 +86,7 @@

   .. code-block:: bash

    (env)$ initialize_tutorial_db development.ini
    (venv)$ initialize_tutorial_db development.ini
    2013-09-06 15:54:08,050 INFO  [sqlalchemy.engine.base.Engine][MainThread] PRAGMA table_info("wikipages")
    2013-09-06 15:54:08,050 INFO  [sqlalchemy.engine.base.Engine][MainThread] ()
    2013-09-06 15:54:08,051 INFO  [sqlalchemy.engine.base.Engine][MainThread]
@@ -113,7 +113,7 @@

    .. code-block:: bash

        (env)$ nosetests .
        (venv)$ nosetests .
        ..
        -----------------------------------------------------------------
        Ran 2 tests in 1.141s
@@ -124,9 +124,9 @@

   .. code-block:: bash

    (env)$ pserve development.ini --reload
    (venv)$ pserve development.ini --reload

#. Open ``http://localhost:6543/`` in a browser.
#. Open http://localhost:6543/ in a browser.

Analysis
========

 docs/quick_tutorial/debugtoolbar.rst

@@ -33,9 +33,9 @@

   .. code-block:: bash

    (env)$ cd ..; cp -r ini debugtoolbar; cd debugtoolbar
    (env)$ python setup.py develop
    (env)$ easy_install pyramid_debugtoolbar
    (venv)$ cd ..; cp -r ini debugtoolbar; cd debugtoolbar
    (venv)$ python setup.py develop
    (venv)$ easy_install pyramid_debugtoolbar


#. Our ``debugtoolbar/development.ini`` gets a configuration entry for
@@ -49,9 +49,9 @@

   .. code-block:: bash

    (env)$ pserve development.ini --reload
    (venv)$ pserve development.ini --reload

#. Open ``http://localhost:6543/`` in your browser. See the handy
#. Open http://localhost:6543/ in your browser. See the handy
   toolbar on the right.

Analysis

 docs/quick_tutorial/forms.rst

@@ -36,7 +36,7 @@

   .. code-block:: bash

    (env)$ cd ..; cp -r view_classes forms; cd forms
    (venv)$ cd ..; cp -r view_classes forms; cd forms

#. Let's edit ``forms/setup.py`` to declare a dependency on Deform
   (which then pulls in Colander as a dependency:
@@ -48,7 +48,7 @@

   .. code-block:: bash

      (env)$ python setup.py develop
      (venv)$ python setup.py develop

#. Register a static view in ``forms/tutorial/__init__.py`` for
   Deform's CSS/JS etc. as well as our demo wikipage scenario's
@@ -88,9 +88,9 @@

   .. code-block:: bash

    (env)$ pserve development.ini --reload
    (venv)$ pserve development.ini --reload

#. Open ``http://localhost:6543/`` in a browser.
#. Open http://localhost:6543/ in a browser.


Analysis

 docs/quick_tutorial/functional_testing.rst

@@ -31,9 +31,9 @@

   .. code-block:: bash

    (env)$ cd ..; cp -r unit_testing functional_testing; cd functional_testing
    (env)$ python setup.py develop
    (env)$ easy_install webtest
    (venv)$ cd ..; cp -r unit_testing functional_testing; cd functional_testing
    (venv)$ python setup.py develop
    (venv)$ easy_install webtest

#. Let's extend ``unit_testing/tutorial/tests.py`` to include a
   functional test:
@@ -46,7 +46,7 @@
   .. code-block:: bash


    (env)$ nosetests tutorial
    (venv)$ nosetests tutorial
    .
    ----------------------------------------------------------------------
    Ran 2 tests in 0.141s

 docs/quick_tutorial/hello_world.rst

@@ -46,7 +46,7 @@

   .. code-block:: bash

    (env)$ mkdir hello_world; cd hello_world
    (venv)$ mkdir hello_world; cd hello_world

#. Copy the following into ``hello_world/app.py``:

@@ -57,9 +57,9 @@

   .. code-block:: bash

    (env)$ python app.py
    (venv)$ python app.py

#. Open ``http://localhost:6543/`` in your browser.
#. Open http://localhost:6543/ in your browser.

Analysis
========

 docs/quick_tutorial/ini.rst

@@ -35,7 +35,7 @@

   .. code-block:: bash

    (env)$ cd ..; cp -r package ini; cd ini
    (venv)$ cd ..; cp -r package ini; cd ini

#. Our ``ini/setup.py`` needs a setuptools "entry point" in the
   ``setup()`` function:
@@ -48,7 +48,7 @@

   .. code-block:: bash

    (env)$ python setup.py develop
    (venv)$ python setup.py develop

#. Let's make a file ``ini/development.ini`` for our configuration:

@@ -66,15 +66,15 @@

   .. code-block:: bash

    (env)$ rm tutorial/app.py
    (venv)$ rm tutorial/app.py

#. Run your Pyramid application with:

   .. code-block:: bash

    (env)$ pserve development.ini --reload
    (venv)$ pserve development.ini --reload

#. Open ``http://localhost:6543/``.
#. Open http://localhost:6543/.

Analysis
========

 docs/quick_tutorial/jinja2.rst

@@ -23,9 +23,9 @@

   .. code-block:: bash

    (env)$ cd ..; cp -r view_classes jinja2; cd jinja2
    (env)$ python setup.py develop
    (env)$ easy_install pyramid_jinja2
    (venv)$ cd ..; cp -r view_classes jinja2; cd jinja2
    (venv)$ python setup.py develop
    (venv)$ easy_install pyramid_jinja2

#. We need to add an item to ``pyramid.includes`` in
   ``jinja2/development.ini``:
@@ -54,15 +54,15 @@

   .. code-block:: bash

    (env)$ nosetests tutorial
    (venv)$ nosetests tutorial

#. Run your Pyramid application with:

   .. code-block:: bash

    (env)$ pserve development.ini --reload
    (venv)$ pserve development.ini --reload

#. Open ``http://localhost:6543/`` in your browser.
#. Open http://localhost:6543/ in your browser.

Analysis
========

 docs/quick_tutorial/json.rst

@@ -28,8 +28,8 @@

   .. code-block:: bash

    (env)$ cd ..; cp -r view_classes json; cd json
    (env)$ python setup.py develop
    (venv)$ cd ..; cp -r view_classes json; cd json
    (venv)$ python setup.py develop

#. We add a new route for ``hello_json`` in
   ``json/tutorial/__init__.py``:
@@ -53,15 +53,15 @@

   .. code-block:: bash

    (env)$ nosetests tutorial
    (venv)$ nosetests tutorial

#. Run your Pyramid application with:

   .. code-block:: bash

    (env)$ pserve development.ini --reload
    (venv)$ pserve development.ini --reload

#. Open ``http://localhost:6543/howdy.json`` in your browser and you
#. Open http://localhost:6543/howdy.json in your browser and you
   will see the resulting JSON response.

Analysis

 docs/quick_tutorial/logging.rst

@@ -32,8 +32,8 @@

   .. code-block:: bash

    (env)$ cd ..; cp -r view_classes logging; cd logging
    (env)$ python setup.py develop
    (venv)$ cd ..; cp -r view_classes logging; cd logging
    (venv)$ python setup.py develop

#. Extend ``logging/tutorial/views.py`` to log a message:

@@ -44,15 +44,15 @@

   .. code-block:: bash

    (env)$ nosetests tutorial
    (venv)$ nosetests tutorial

#. Run your Pyramid application with:

   .. code-block:: bash

    (env)$ pserve development.ini --reload
    (venv)$ pserve development.ini --reload

#. Open ``http://localhost:6543/`` and ``http://localhost:6543/howdy``
#. Open http://localhost:6543/ and http://localhost:6543/howdy
   in your browser. Note, both in the console and in the debug
   toolbar, the message that you logged.

@@ -67,7 +67,7 @@

In this, our ``tutorial`` Python package is setup as a logger
and configured to log messages at a ``DEBUG`` or higher level. When you
visit ``http://localhost:6543`` your console will now show::
visit http://localhost:6543 your console will now show::

 2013-08-09 10:42:42,968 DEBUG [tutorial.views][MainThread] In home view


 docs/quick_tutorial/more_view_classes.rst

@@ -55,8 +55,8 @@

   .. code-block:: bash

    (env)$ cd ..; cp -r templating more_view_classes; cd more_view_classes
    (env)$ python setup.py develop
    (venv)$ cd ..; cp -r templating more_view_classes; cd more_view_classes
    (venv)$ python setup.py develop

#. Our route in ``more_view_classes/tutorial/__init__.py`` needs some
   replacement patterns:
@@ -98,9 +98,9 @@

   .. code-block:: bash

    (env)$ pserve development.ini --reload
    (venv)$ pserve development.ini --reload

#. Open ``http://localhost:6543/howdy/jane/doe`` in your browser. Click
#. Open http://localhost:6543/howdy/jane/doe in your browser. Click
   the ``Save`` and ``Delete`` buttons and watch the output in the
   console window.

@@ -110,7 +110,7 @@
As you can see, the four views are logically grouped together.
Specifically:

- We have a ``home`` view available at ``http://localhost:6543/`` with
- We have a ``home`` view available at http://localhost:6543/ with
  a clickable link to the ``hello`` view.

- The second view is returned when you go to ``/howdy/jane/doe``. This

 docs/quick_tutorial/package.rst

@@ -56,7 +56,7 @@

   .. code-block:: bash

    (env)$ cd ..; mkdir package; cd package
    (venv)$ cd ..; mkdir package; cd package

#. In ``package/setup.py``, enter the following:

@@ -67,8 +67,8 @@

   .. code-block:: bash

    (env)$ python setup.py develop
    (env)$ mkdir tutorial
    (venv)$ python setup.py develop
    (venv)$ mkdir tutorial

#. Enter the following into ``package/tutorial/__init__.py``:

@@ -82,9 +82,9 @@

   .. code-block:: bash

    (env)$ python tutorial/app.py
    (venv)$ python tutorial/app.py

#. Open ``http://localhost:6543/`` in your browser.
#. Open http://localhost:6543/ in your browser.

Analysis
========

 docs/quick_tutorial/python_setup.rst

@@ -14,9 +14,9 @@

.. code-block:: bash

  $ pyvenv-3.3 env33
  $ source env33/bin/activate
  $ wget https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py -O - | python
  $ pyvenv-3.3 venv
  $ source env/bin/activate
  (venv)$ wget https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py -O - | python

If ``wget`` complains with a certificate error, run it with:

@@ -26,7 +26,7 @@

In these steps above we first made a :term:`virtualenv` and then
"activated"  it, which adjusted our path to look first in
``env33/bin`` for commands (such as ``python``). We next downloaded
``venv/bin`` for commands (such as ``python``). We next downloaded
Python's packaging support and installed it, giving us the
``easy_install`` command-line script for adding new packages. Python
2.7 users will need to use ``virtualenv`` instead of ``pyvenv`` to make

 docs/quick_tutorial/request_response.rst

@@ -38,8 +38,8 @@

   .. code-block:: bash

    (env)$ cd ..; cp -r view_classes request_response; cd request_response
    (env)$ python setup.py develop
    (venv)$ cd ..; cp -r view_classes request_response; cd request_response
    (venv)$ python setup.py develop

#. Simplify the routes in ``request_response/tutorial/__init__.py``:

@@ -57,18 +57,18 @@

   .. code-block:: bash

    (env)$ nosetests tutorial
    (venv)$ nosetests tutorial

#. Run your Pyramid application with:

   .. code-block:: bash

    (env)$ pserve development.ini --reload
    (venv)$ pserve development.ini --reload

#. Open ``http://localhost:6543/`` in your browser. You will be
   redirected to ``http://localhost:6543/plain``
#. Open http://localhost:6543/ in your browser. You will be
   redirected to http://localhost:6543/plain

#. Open ``http://localhost:6543/plain?name=alice`` in your browser.
#. Open http://localhost:6543/plain?name=alice in your browser.

Analysis
========
@@ -79,7 +79,7 @@
special object from a view or raising a special exception.

In this Pyramid view, we get the URL being visited from ``request.url``.
Also, if you visited ``http://localhost:6543/plain?name=alice``,
Also, if you visited http://localhost:6543/plain?name=alice,
the name is included in the body of the response::

  URL http://localhost:6543/plain?name=alice with name: alice

 docs/quick_tutorial/routing.rst

@@ -45,8 +45,8 @@

   .. code-block:: bash

    (env)$ cd ..; cp -r view_classes routing; cd routing
    (env)$ python setup.py develop
    (venv)$ cd ..; cp -r view_classes routing; cd routing
    (venv)$ python setup.py develop

#. Our ``routing/tutorial/__init__.py`` needs a route with a replacement
   pattern:
@@ -74,15 +74,15 @@

   .. code-block:: bash

    (env)$ nosetests tutorial
    (venv)$ nosetests tutorial

#. Run your Pyramid application with:

   .. code-block:: bash

    (env)$ pserve development.ini --reload
    (venv)$ pserve development.ini --reload

#. Open ``http://localhost:6543/howdy/amy/smith`` in your browser.
#. Open http://localhost:6543/howdy/amy/smith in your browser.

Analysis
========
@@ -112,7 +112,7 @@
============

#. What happens if you to go the URL
   ``http://localhost:6543/howdy``? Is this the result that you
   http://localhost:6543/howdy? Is this the result that you
   expected?

.. seealso:: `Weird Stuff You Can Do With URL

 docs/quick_tutorial/scaffolds.rst

@@ -33,7 +33,7 @@

    .. code-block:: bash

        (env)$ pcreate --list
        (venv)$ pcreate --list
        Available scaffolds:
          alchemy:                 Pyramid SQLAlchemy project using url dispatch
          starter:                 Pyramid starter project
@@ -43,21 +43,21 @@

    .. code-block:: bash

        (env)$ pcreate --scaffold starter scaffolds
        (venv)$ pcreate --scaffold starter scaffolds

#. Use normal Python development to setup our project for development:

    .. code-block:: bash

        (env)$ cd scaffolds
        (env)$ python setup.py develop
        (venv)$ cd scaffolds
        (venv)$ python setup.py develop

#. Startup the application by pointing Pyramid's ``pserve`` command at
   the project's (generated) configuration file:

    .. code-block:: bash

        (env)$ pserve development.ini --reload
        (venv)$ pserve development.ini --reload

   On startup, ``pserve`` logs some output:

@@ -67,7 +67,7 @@
     Starting server in PID 72213.
     Starting HTTP server on http://0.0.0.0:6543

#. Open ``http://localhost:6543/`` in your browser.
#. Open http://localhost:6543/ in your browser.

Analysis
========

 docs/quick_tutorial/sessions.rst

@@ -31,8 +31,8 @@

   .. code-block:: bash

    (env)$ cd ..; cp -r view_classes sessions; cd sessions
    (env)$ python setup.py develop
    (venv)$ cd ..; cp -r view_classes sessions; cd sessions
    (venv)$ python setup.py develop

#. Our ``sessions/tutorial/__init__.py`` needs a choice of session
   factory to get registered with the :term:`configurator`:
@@ -56,15 +56,15 @@

   .. code-block:: bash

    (env)$ nosetests tutorial
    (venv)$ nosetests tutorial

#. Run your Pyramid application with:

   .. code-block:: bash

    (env)$ pserve development.ini --reload
    (venv)$ pserve development.ini --reload

#. Open ``http://localhost:6543/`` and ``http://localhost:6543/howdy``
#. Open http://localhost:6543/ and http://localhost:6543/howdy
   in your browser. As you reload and switch between those URLs, note
   that the counter increases and is *not* specific to the URL.


 docs/quick_tutorial/static_assets.rst

@@ -20,8 +20,8 @@

   .. code-block:: bash

    (env)$ cd ..; cp -r view_classes static_assets; cd static_assets
    (env)$ python setup.py develop
    (venv)$ cd ..; cp -r view_classes static_assets; cd static_assets
    (venv)$ python setup.py develop

#. We add a call ``config.add_static_view in
   ``static_assets/tutorial/__init__.py``:
@@ -45,21 +45,21 @@

   .. code-block:: bash

    (env)$ nosetests tutorial
    (venv)$ nosetests tutorial

#. Run your Pyramid application with:

   .. code-block:: bash

    (env)$ pserve development.ini --reload
    (venv)$ pserve development.ini --reload

#. Open ``http://localhost:6543/`` in your browser.
#. Open http://localhost:6543/ in your browser.

Analysis
========

We changed our WSGI application to map requests under
``http://localhost:6543/static/`` to files and directories inside a
http://localhost:6543/static/ to files and directories inside a
``static`` directory inside our ``tutorial`` package. This directory
contained ``app.css``.


 docs/quick_tutorial/templating.rst

@@ -36,8 +36,8 @@

   .. code-block:: bash

    (env)$ cd ..; cp -r views templating; cd templating
    (env)$ python setup.py develop
    (venv)$ cd ..; cp -r views templating; cd templating
    (venv)$ python setup.py develop

#. Our ``templating/tutorial/views.py`` no longer has HTML in it:

@@ -66,7 +66,7 @@
   .. code-block:: bash


    (env)$ nosetests tutorial
    (venv)$ nosetests tutorial
    .
    ----------------------------------------------------------------------
    Ran 4 tests in 0.141s
@@ -77,9 +77,9 @@

   .. code-block:: bash

    (env)$ pserve development.ini --reload
    (venv)$ pserve development.ini --reload

#. Open ``http://localhost:6543/`` and ``http://localhost:6543/howdy``
#. Open http://localhost:6543/ and http://localhost:6543/howdy
   in your browser.

Analysis

 docs/quick_tutorial/unit_testing.rst

@@ -45,9 +45,9 @@

   .. code-block:: bash

    (env)$ cd ..; cp -r debugtoolbar unit_testing; cd unit_testing
    (env)$ python setup.py develop
    (env)$ easy_install nose
    (venv)$ cd ..; cp -r debugtoolbar unit_testing; cd unit_testing
    (venv)$ python setup.py develop
    (venv)$ easy_install nose

#. Now we write a simple unit test in ``unit_testing/tutorial/tests.py``:

@@ -59,7 +59,7 @@
   .. code-block:: bash


    (env)$ nosetests tutorial
    (venv)$ nosetests tutorial
    .
    ----------------------------------------------------------------------
    Ran 1 test in 0.141s

 docs/quick_tutorial/view_classes.rst

@@ -39,8 +39,8 @@

   .. code-block:: bash

    (env)$ cd ..; cp -r templating view_classes; cd view_classes
    (env)$ python setup.py develop
    (venv)$ cd ..; cp -r templating view_classes; cd view_classes
    (venv)$ python setup.py develop

#. Our ``view_classes/tutorial/views.py`` now has a view class with
   our two views:
@@ -60,7 +60,7 @@
   .. code-block:: bash


    (env)$ nosetests tutorial
    (venv)$ nosetests tutorial
    .
    ----------------------------------------------------------------------
    Ran 4 tests in 0.141s
@@ -71,9 +71,9 @@

   .. code-block:: bash

    (env)$ pserve development.ini --reload
    (venv)$ pserve development.ini --reload

#. Open ``http://localhost:6543/`` and ``http://localhost:6543/howdy``
#. Open http://localhost:6543/ and http://localhost:6543/howdy
   in your browser.

Analysis

 docs/quick_tutorial/views.rst

@@ -40,8 +40,8 @@

   .. code-block:: bash

    (env)$ cd ..; cp -r function_testing views; cd views
    (env)$ python setup.py develop
    (venv)$ cd ..; cp -r function_testing views; cd views
    (venv)$ python setup.py develop

#. Our ``views/tutorial/__init__.py`` gets a lot shorter:

@@ -64,7 +64,7 @@
   .. code-block:: bash


    (env)$ nosetests tutorial
    (venv)$ nosetests tutorial
    .
    ----------------------------------------------------------------------
    Ran 4 tests in 0.141s
@@ -75,9 +75,9 @@

   .. code-block:: bash

    (env)$ pserve development.ini --reload
    (venv)$ pserve development.ini --reload

#. Open ``http://localhost:6543/`` and ``http://localhost:6543/howdy``
#. Open http://localhost:6543/ and http://localhost:6543/howdy
   in your browser.

Analysis
@@ -89,7 +89,7 @@
module ``views.py`` which is scanned via ``config.scan('.views')``.

We have 2 views, each leading to the other. If you start at
``http://localhost:6543/``, you get a response with a link to the next
http://localhost:6543/, you get a response with a link to the next
view. The ``hello_view`` (available at the URL ``/howdy``) has a link
back to the first view.