Merge remote-tracking branch 'upstream/master' into shentonfreude/bug.sqltut-test-populate-settings

5 files changed, 141 insertions, 3 deletions

diff --git a/docs/tutorials/wiki/definingmodels.rst b/docs/tutorials/wiki/definingmodels.rst
index cdf3b6092..982d6ea74 100644
--- a/docs/tutorials/wiki/definingmodels.rst
+++ b/docs/tutorials/wiki/definingmodels.rst
@@ -88,7 +88,8 @@ View the Application in a Browser
 
 We can't.  At this point, our system is in a "non-runnable" state; we'll need
 to change view-related files in the next chapter to be able to start the
-application successfully.  If you try to start the application, you'll wind
+application successfully.  If you try to start the application (See
+:ref:`wiki-start-the-application`), you'll wind
 up with a Python traceback on your console that ends with this exception:
 
 .. code-block:: text
diff --git a/docs/tutorials/wiki/definingviews.rst b/docs/tutorials/wiki/definingviews.rst
index 371cae8eb..53e60fda3 100644
--- a/docs/tutorials/wiki/definingviews.rst
+++ b/docs/tutorials/wiki/definingviews.rst
@@ -301,8 +301,8 @@ subdirectories) and are just referred to by URL.
 Viewing the Application in a Browser
 ====================================
 
-We can finally examine our application in a
-browser.  The views we'll try are as follows:
+We can finally examine our application in a browser (See
+:ref:`wiki-start-the-application`).  The views we'll try are as follows:
 
 - Visiting ``http://localhost:6543/`` in a browser invokes the ``view_wiki``
   view.  This always redirects to the ``view_page`` view of the ``FrontPage``
diff --git a/docs/tutorials/wiki/design.rst b/docs/tutorials/wiki/design.rst
new file mode 100644
index 000000000..ea7076f60
--- /dev/null
+++ b/docs/tutorials/wiki/design.rst
@@ -0,0 +1,134 @@
+==========
+Design
+==========
+
+Following is a quick overview of our wiki application, to help
+us understand the changes that we will be doing next in our
+default files generated by the paster scafffold.
+
+Overall
+-------
+
+We choose to use ``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.
+
+Models
+------
+
+The root resource, named *Wiki*, will be a mapping of wiki page
+names to page resources.  The page resources will be instances
+of a *Page* class and they store the text content.
+
+URLs like ``/PageName`` will be traversed using  Wiki[
+*PageName* ] => page, and the context that results is the page
+resource of an existing page.
+
+To add a page to the wiki, a new instance of the page resource
+is created and its name and reference are added to the Wiki
+mapping.
+
+A page named *FrontPage* containing the text *This is the front
+page*, will be created when the storage is initialized, and will
+be used as the wiki home page.
+
+Views
+-----
+
+There will be four views to handle the normal operations of
+viewing, editing and adding wiki pages.  Two additional views
+will handle the login and logout tasks related to security.
+
+Security
+--------
+
+- USERS, a dictionary mapping users names to their
+  corresponding passwords.
+- GROUPS, a dictionary mapping user names to a 
+  list of groups they belong to.
+- *groupfinder*, an *authorization callback* that looks up
+  USERS and GROUPS.  It will be provided in a new
+  *security.py* file.
+- An :term:`ACL` is attached to the root resource.  Each
+  row below details an :term:`ACE`:
+
+  +----------+----------------+----------------+
+  | Action   | Principal      | Permission     |
+  +==========+================+================+
+  | Allow    | Everyone       | View           |
+  +----------+----------------+----------------+
+  | Allow    | group:editors  | Edit           |
+  +----------+----------------+----------------+
+
+- Permission declarations for the views.
+
+
+Summary
+-------
+
+The URL, context, actions, template and permission associated to each view are
+listed in the following table:
+
++----------------------+-------------+-----------------+-----------------------+------------+------------+
+| URL                  |  View       |  Context        |  Action               |  Template  | Permission |
+|                      |             |                 |                       |            |            |
++======================+=============+=================+=======================+============+============+
+| /                    |  view_wiki  |  Wiki           |  Redirect to          |            |            |
+|                      |             |                 |  /FrontPage           |            |            |
++----------------------+-------------+-----------------+-----------------------+------------+------------+
+| /PageName            |  view_page  |  Page           |  Display existing     |  view.pt   |  view      |
+|                      |  [1]_       |                 |  page [2]_            |            |            |
+|                      |             |                 |                       |            |            |
+|                      |             |                 |                       |            |            |
+|                      |             |                 |                       |            |            |
++----------------------+-------------+-----------------+-----------------------+------------+------------+
+| /PageName/edit_page  |  edit_page  |  Page           |  Display edit form    |  edit.pt   |  edit      |
+|                      |             |                 |  with existing        |            |            |
+|                      |             |                 |  content.             |            |            |
+|                      |             |                 |                       |            |            |
+|                      |             |                 |  If the form was      |            |            |
+|                      |             |                 |  submitted, redirect  |            |            |
+|                      |             |                 |  to /PageName         |            |            |
++----------------------+-------------+-----------------+-----------------------+------------+------------+
+| /add_page/PageName   |  add_page   |  Wiki           |  Create the page      |  edit.pt   |  edit      |
+|                      |             |                 |  *PageName* in        |            |            |
+|                      |             |                 |  storage,  display    |            |            |
+|                      |             |                 |  the edit form        |            |            |
+|                      |             |                 |  without content.     |            |            |
+|                      |             |                 |                       |            |            |
+|                      |             |                 |  If the form was      |            |            |
+|                      |             |                 |  submitted,           |            |            |
+|                      |             |                 |  redirect to          |            |            |
+|                      |             |                 |  /PageName            |            |            |
++----------------------+-------------+-----------------+-----------------------+------------+------------+
+| /login               |  login      |  Wiki,          |  Display login form.  |  login.pt  |            |
+|                      |             |  Forbidden [3]_ |                       |            |            |
+|                      |             |                 |  If the form was      |            |            |
+|                      |             |                 |  submitted,           |            |            |
+|                      |             |                 |  authenticate.        |            |            |
+|                      |             |                 |                       |            |            |
+|                      |             |                 |  - If authentication  |            |            |
+|                      |             |                 |    successful,        |            |            |
+|                      |             |                 |    redirect to the    |            |            |
+|                      |             |                 |    page that we       |            |            |
+|                      |             |                 |    came from.         |            |            |
+|                      |             |                 |                       |            |            |
+|                      |             |                 |  - If authentication  |            |            |
+|                      |             |                 |    fails, display     |            |            |
+|                      |             |                 |    login form with    |            |            |
+|                      |             |                 |    "login failed"     |            |            |
+|                      |             |                 |    message.           |            |            |
+|                      |             |                 |                       |            |            |
++----------------------+-------------+-----------------+-----------------------+------------+------------+
+| /logout              |  logout     |  Wiki           |  Redirect to          |            |            |
+|                      |             |                 |  /FrontPage           |            |            |
++----------------------+-------------+-----------------+-----------------------+------------+------------+
+
+.. [1] This is the default view for a Page context
+       when there is no view name.
+.. [2] Pyramid will return a default 404 Not Found page
+       if the page *PageName* does not exist yet.
+.. [3] pyramid.exceptions.Forbidden is reached when a
+       user tries to invoke a view that is
+       not authorized by the authorization policy.
diff --git a/docs/tutorials/wiki/index.rst b/docs/tutorials/wiki/index.rst
index 3edc6ba04..f07f45bd0 100644
--- a/docs/tutorials/wiki/index.rst
+++ b/docs/tutorials/wiki/index.rst
@@ -18,6 +18,7 @@ tutorial can be browsed at
    :maxdepth: 2
 
    background
+   design
    installation
    basiclayout
    definingmodels
diff --git a/docs/tutorials/wiki/installation.rst b/docs/tutorials/wiki/installation.rst
index 330b17c86..63b30da5a 100644
--- a/docs/tutorials/wiki/installation.rst
+++ b/docs/tutorials/wiki/installation.rst
@@ -228,6 +228,8 @@ Looks like the code in the ``zodb`` scaffold for ZODB projects is
 missing some test coverage, particularly in the file named
 ``models.py``.
 
+.. _wiki-start-the-application:
+
 Start the Application
 =====================