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

5 files changed, 38 insertions, 36 deletions

diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst
index 4f73dc914..ed98da183 100644
--- a/docs/tutorials/wiki2/basiclayout.rst
+++ b/docs/tutorials/wiki2/basiclayout.rst
@@ -45,7 +45,7 @@ When you invoke the ``pserve development.ini`` command, the ``main`` function
 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 @@ engine:
       :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 @@ two arguments: ``static`` (the name), and ``static`` (the path):
       :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 @@ used when the URL is ``/``:
 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 @@ Let's examine this in detail. First, we need some imports to support later code:
       :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 @@ To give a simple example of a  model class, we define one named ``MyModel``:
       :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.
diff --git a/docs/tutorials/wiki2/definingmodels.rst b/docs/tutorials/wiki2/definingmodels.rst
index 1653faf4a..2e6c74c99 100644
--- a/docs/tutorials/wiki2/definingmodels.rst
+++ b/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 @@ Making Edits to ``models.py``
 
 .. 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 @@ this class inherits from an instance of
 
 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
diff --git a/docs/tutorials/wiki2/definingviews.rst b/docs/tutorials/wiki2/definingviews.rst
index a54996e3c..c23ca947d 100644
--- a/docs/tutorials/wiki2/definingviews.rst
+++ b/docs/tutorials/wiki2/definingviews.rst
@@ -26,7 +26,7 @@ Declaring Dependencies in Our ``setup.py`` File
 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 @@ the :class:`pyramid.interfaces.IResponse` interface like
 
 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 @@ compiled regular expression.
    :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 @@ the page we'd like to add.  If our add view is invoked via,
 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
@@ -191,13 +198,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 @@ matching the name of the page the user wants to edit.
    :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
 ================
 
diff --git a/docs/tutorials/wiki2/design.rst b/docs/tutorials/wiki2/design.rst
index 6e41e00aa..c56d7fecf 100644
--- a/docs/tutorials/wiki2/design.rst
+++ b/docs/tutorials/wiki2/design.rst
@@ -9,7 +9,7 @@ tutorial.
 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.
diff --git a/docs/tutorials/wiki2/installation.rst b/docs/tutorials/wiki2/installation.rst
index 6589a1557..4ab02a13a 100644
--- a/docs/tutorials/wiki2/installation.rst
+++ b/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 @@ Installing the Project in "Development Mode"
 
 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 @@ test`` does but provides additional "coverage" information, exposing
 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: