A bunch of minor tweaks to the wiki2 tutorial in docs/tutorials/wiki2

Marc Abramowitz

2012-11-30 b9b2ee39c251dd68a12e717e1f6d9d02a29efe9a

A bunch of minor tweaks to the wiki2 tutorial in docs/tutorials/wiki2

 docs/tutorials/wiki2/basiclayout.rst

@@ -45,7 +45,7 @@
above is executed.  It accepts some settings and returns a :term:`WSGI`
application.  (See :ref:`startup_chapter` for more about ``pserve``.)

The main function first creates a SQLAlchemy database engine using
The main function first creates a :term:`SQLAlchemy` database engine using
``engine_from_config`` from the ``sqlalchemy.`` prefixed settings in the
``development.ini`` file's ``[app:main]`` section.  This will be a URI
(something like ``sqlite://``):
@@ -62,7 +62,7 @@
      :lines: 13
      :language: py

``main`` subsequently initializes our SQLAlchemy declarative Base object,
``main`` subsequently initializes our SQLAlchemy declarative ``Base`` object,
assigning the engine we created to the ``bind`` attribute of it's
``metadata`` object.  This allows table definitions done imperatively
(instead of declaratively, via a class statement) to work.  We won't use any
@@ -94,9 +94,9 @@
      :language: py

This registers a static resource view which will match any URL that starts
with the prefix ``/static`` (by virtue of the first argument to add_static
view).  This will serve up static resources for us from within the ``static``
directory of our ``tutorial`` package, in this case, via
with the prefix ``/static`` (by virtue of the first argument to
``add_static_view``).  This will serve up static resources for us from within
the ``static`` directory of our ``tutorial`` package, in this case, via
``http://localhost:6543/static/`` and below (by virtue of the second argument
to add_static_view).  With this declaration, we're saying that any URL that
starts with ``/static`` should go to the static view; any remainder of its
@@ -114,8 +114,9 @@
Since this route has a ``pattern`` equalling ``/`` it is the route that will
be matched when the URL ``/`` is visited, e.g. ``http://localhost:6543/``.

``main`` next calls the ``scan`` method of the configurator, which will
recursively scan our ``tutorial`` package, looking for ``@view_config`` (and
``main`` next calls the ``scan`` method of the configurator
(:meth:`pyramid.config.Configurator.scan`), which will recursively scan our
``tutorial`` package, looking for ``@view_config`` (and
other special) decorators.  When it finds a ``@view_config`` decorator, a
view configuration will be registered, which will allow one of our
application URLs to be mapped to some code.
@@ -197,7 +198,7 @@
      :linenos:
      :language: py

Next we set up a SQLAlchemy "DBSession" object:
Next we set up a SQLAlchemy ``DBSession`` object:

   .. literalinclude:: src/basiclayout/tutorial/models.py
      :lines: 16
@@ -230,8 +231,9 @@
      :linenos:
      :language: py

Our example model has an ``__init__`` that takes a two arguments (``name``,
and ``value``).  It stores these values as ``self.name`` and ``self.value``
Our example model has an ``__init__`` method that takes a two arguments
(``name``, and ``value``).  It stores these values as ``self.name`` and
``self.value``
within the ``__init__`` function itself.  The ``MyModel`` class also has a
``__tablename__`` attribute.  This informs SQLAlchemy which table to use to
store the data representing instances of this class.

 docs/tutorials/wiki2/definingmodels.rst

@@ -2,7 +2,7 @@
Defining the Domain Model
=========================

The first change we'll make to our stock pcreate-generated application will
The first change we'll make to our stock ``pcreate``-generated application will
be to define a :term:`domain model` constructor representing a wiki page.
We'll do this inside our ``models.py`` file.

@@ -15,7 +15,7 @@

.. note::

  There is nothing automagically special about the filename ``models.py``.  A
  There is nothing special about the filename ``models.py``.  A
  project may have many models throughout its codebase in arbitrarily-named
  files.  Files implementing models often have ``model`` in their filenames
  (or they may live in a Python subpackage of your application package named
@@ -46,8 +46,8 @@

As you can see, our ``Page`` class has a class level attribute
``__tablename__`` which equals the string ``'pages'``.  This means that
SQLAlchemy will store our wiki data in a SQL table named ``pages``.  Our Page
class will also have class-level attributes named ``id``, ``name`` and
SQLAlchemy will store our wiki data in a SQL table named ``pages``.  Our
``Page`` class will also have class-level attributes named ``id``, ``name`` and
``data`` (all instances of :class:`sqlalchemy.Column`).  These will map to
columns in the ``pages`` table.  The ``id`` attribute will be the primary key
in the table.  The ``name`` attribute will be a text attribute, each value of

 docs/tutorials/wiki2/definingviews.rst

@@ -26,7 +26,7 @@
The view code in our application will depend on a package which is not a
dependency of the original "tutorial" application.  The original "tutorial"
application was generated by the ``pcreate`` command; it doesn't know
about our custom application requirements.  
about our custom application requirements.

We need to add a dependency on the ``docutils`` package to our ``tutorial``
package's ``setup.py`` file by assigning this dependency to the ``requires`` parameter in ``setup()``.
@@ -123,14 +123,14 @@

It uses the :meth:`pyramid.request.Request.route_url` API to construct a 
URL to the ``FrontPage`` page (e.g. ``http://localhost:6543/FrontPage``), which 
is used as the "location" of the HTTPFound response, forming an HTTP redirect.
is used as the "location" of the ``HTTPFound`` response, forming an HTTP redirect.

The ``view_page`` view function
-------------------------------

``view_page()`` is used to display a single page of our
wiki.  It renders the :term:`ReStructuredText` body of a page (stored as
the ``data`` attribute of a Page object) as HTML.  Then it substitutes an
the ``data`` attribute of a ``Page`` model object) as HTML.  Then it substitutes an
HTML anchor for each *WikiWord* reference in the rendered HTML using a
compiled regular expression.

@@ -139,7 +139,7 @@
   :linenos:
   :language: python

The curried ``check()`` function is used as the first argument to
The ``check()`` function is used as the first argument to
``wikiwords.sub``, indicating that it should be called to provide a value for
each WikiWord match found in the content.  If the wiki already contains a
page with the matched WikiWord name, ``check()`` generates a view
@@ -181,6 +181,13 @@
e.g. ``http://localhost:6543/add_page/SomeName``, the value for
``'pagename'`` in the ``matchdict`` will be ``'SomeName'``.

If the view execution *is* a result of a form submission (i.e. the expression
``'form.submitted' in request.params`` is ``True``), we scrape the page body
from the form data, create a Page object with this page body and the name
taken from ``matchdict['pagename']``, and save it into the database using
``DBSession.add``.  We then redirect back to the ``view_page`` view for the
newly created page.

If the view execution is *not* a result of a form submission (i.e. the
expression ``'form.submitted' in request.params`` is ``False``), the view
callable renders a template.  To do so, it generates a "save url" which the
@@ -190,13 +197,6 @@
in order to satisfy the edit form's desire to have *some* page object
exposed as ``page``. :app:`Pyramid` will render the template associated
with this view to a response.

If the view execution *is* a result of a form submission (i.e. the expression
``'form.submitted' in request.params`` is ``True``), we scrape the page body
from the form data, create a Page object with this page body and the name
taken from ``matchdict['pagename']``, and save it into the database using
``DBSession.add``.  We then redirect back to the ``view_page`` view for the
newly created page.

The ``edit_page`` view function
-------------------------------
@@ -212,17 +212,17 @@
   :linenos:
   :language: python

If the view execution is *not* a result of a form submission (i.e. the
expression ``'form.submitted' in request.params`` is ``False``), the view
simply renders the edit form, passing the page object and a ``save_url``
which will be used as the action of the generated form.

If the view execution *is* a result of a form submission (i.e. the expression
``'form.submitted' in request.params`` is ``True``), the view grabs the
``body`` element of the request parameters and sets it as the ``data``
attribute of the page object.  It then redirects to the ``view_page`` view
of the wiki page.

If the view execution is *not* a result of a form submission (i.e. the
expression ``'form.submitted' in request.params`` is ``False``), the view
simply renders the edit form, passing the page object and a ``save_url``
which will be used as the action of the generated form.

Adding Templates
================


 docs/tutorials/wiki2/design.rst

@@ -9,7 +9,7 @@
Overall
-------

We choose to use ``reStructuredText`` markup in the wiki text.  Translation
We choose to use :term:`reStructuredText` markup in the wiki text.  Translation
from reStructuredText to HTML is provided by the widely used ``docutils``
Python module.  We will add this module in the dependency list on the project
``setup.py`` file.

 docs/tutorials/wiki2/installation.rst

@@ -2,7 +2,7 @@
Installation
============

This tutorial assumes that Python and virtualenv are already installed
This tutorial assumes that Python and :term:`virtualenv` are already installed
and working in your system. If you need help setting this up, you should
refer to the chapters on :ref:`installing_chapter`.

@@ -98,9 +98,9 @@

In order to do development on the project easily, you must "register"
the project as a development egg in your workspace using the
``setup.py develop`` command.  In order to do so, cd to the "tutorial"
``setup.py develop`` command.  In order to do so, cd to the `tutorial`
directory you created in :ref:`sql_making_a_project`, and run the
"setup.py develop" command using virtualenv Python interpreter.
``setup.py develop`` command using the virtualenv Python interpreter.

On UNIX:

@@ -158,8 +158,8 @@
which lines of your project are "covered" (or not covered) by the
tests.

To get this functionality working, we'll need to install a couple of
other packages into our ``virtualenv``: ``nose`` and ``coverage``:
To get this functionality working, we'll need to install the ``nose`` and
``coverage`` packages into our ``virtualenv``:

On UNIX: