Merge pull request #485 from ppaez/improve-docs

Improve docs

16 files changed, 121 insertions, 155 deletions

diff --git a/docs/tutorials/wiki2/definingmodels.rst b/docs/tutorials/wiki2/definingmodels.rst
index 0810ad1c5..81fd81156 100644
--- a/docs/tutorials/wiki2/definingmodels.rst
+++ b/docs/tutorials/wiki2/definingmodels.rst
@@ -54,48 +54,48 @@ in the table.  The ``name`` attribute will be a text attribute, each value of
 which needs to be unique within the column.  The ``data`` attribute is a text
 attribute that will hold the body of each page.
 
-Changing ``scripts/populate.py``
---------------------------------
+Changing ``scripts/initializedb.py``
+------------------------------------
 
 We haven't looked at the guts of this file yet, but within the ``scripts``
-directory of your ``tutorial`` package is a file named ``populate.py``.  Code
-in this file is executed whenever we run the ``populate_tutorial`` command
+directory of your ``tutorial`` package is a file named ``initializedb.py``.  Code
+in this file is executed whenever we run the ``initialize_tutorial_db`` command
 (as we did in the installation step of this tutorial).
 
-Since we've changed our model, we need to make changes to our ``populate.py``
+Since we've changed our model, we need to make changes to our ``initializedb.py``
 script.  In particular, we'll replace our import of ``MyModel`` with one of
 ``Page`` and we'll change the very end of the script to create a ``Page``
 rather than a ``MyModel`` and add it to our ``DBSession``.
 
-Open ``tutorial/tutorial/scripts/populate.py`` and edit it to look like the 
+Open ``tutorial/tutorial/scripts/initializedb.py`` and edit it to look like the 
 following:
 
-.. literalinclude:: src/models/tutorial/scripts/populate.py
+.. literalinclude:: src/models/tutorial/scripts/initializedb.py
    :linenos:
    :language: python
    :emphasize-lines: 14,34
 
 (Only the highlighted lines need to be changed.)
 
-Repopulating the Database
--------------------------
+Reinitializing the Database
+---------------------------
 
-Because our model has changed, in order to repopulate the database, we need
-to rerun the ``populate_tutorial`` command to pick up the changes you've made
-to both the models.py file and to the populate.py file.  From the root of the
+Because our model has changed, in order to reinitialize the database, we need
+to rerun the ``initialize_tutorial_db`` command to pick up the changes you've made
+to both the models.py file and to the initializedb.py file.  From the root of the
 ``tutorial`` project, directory execute the following commands.
 
 On UNIX:
 
 .. code-block:: text
 
-   $ ../bin/populate_tutorial development.ini
+   $ ../bin/initialize_tutorial_db development.ini
 
 On Windows:
 
 .. code-block:: text
 
-   c:\pyramidtut\tutorial> ..\Scripts\populate_tutorial development.ini
+   c:\pyramidtut\tutorial> ..\Scripts\initialize_tutorial_db development.ini
 
 Success will look something like this::
 
diff --git a/docs/tutorials/wiki2/design.rst b/docs/tutorials/wiki2/design.rst
index ade40ab18..36c4f19bc 100644
--- a/docs/tutorials/wiki2/design.rst
+++ b/docs/tutorials/wiki2/design.rst
@@ -65,63 +65,63 @@ Security
 Summary
 -------
 
-The URL, context, actions, template and permission associated to each view are
+The URL, 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]_            |            |            |
-|                      |             |                 |                       |            |            |
-|                      |             |                 |                       |            |            |
-|                      |             |                 |                       |            |            |
-+----------------------+-------------+-----------------+-----------------------+------------+------------+
-| /edit_page/PageName  |  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           |            |            |
-+----------------------+-------------+-----------------+-----------------------+------------+------------+
++----------------------+-----------------------+-------------+------------+------------+
+| URL                  |  Action               |  View       |  Template  | Permission |
+|                      |                       |             |            |            |
++======================+=======================+=============+============+============+
+| /                    |  Redirect to          |  view_wiki  |            |            |
+|                      |  /FrontPage           |             |            |            |
++----------------------+-----------------------+-------------+------------+------------+
+| /PageName            |  Display existing     |  view_page  |  view.pt   |  view      |
+|                      |  page [2]_            |  [1]_       |            |            |
+|                      |                       |             |            |            |
+|                      |                       |             |            |            |
+|                      |                       |             |            |            |
++----------------------+-----------------------+-------------+------------+------------+
+| /edit_page/PageName  |  Display edit form    |  edit_page  |  edit.pt   |  edit      |
+|                      |  with existing        |             |            |            |
+|                      |  content.             |             |            |            |
+|                      |                       |             |            |            |
+|                      |  If the form was      |             |            |            |
+|                      |  submitted, redirect  |             |            |            |
+|                      |  to /PageName         |             |            |            |
++----------------------+-----------------------+-------------+------------+------------+
+| /add_page/PageName   |  Create the page      |  add_page   |  edit.pt   |  edit      |
+|                      |  *PageName* in        |             |            |            |
+|                      |  storage,  display    |             |            |            |
+|                      |  the edit form        |             |            |            |
+|                      |  without content.     |             |            |            |
+|                      |                       |             |            |            |
+|                      |  If the form was      |             |            |            |
+|                      |  submitted,           |             |            |            |
+|                      |  redirect to          |             |            |            |
+|                      |  /PageName            |             |            |            |
++----------------------+-----------------------+-------------+------------+------------+
+| /login               |  Display login form.  |  login      |  login.pt  |            |
+|                      |                       |             |            |            |
+|                      |  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              |  Redirect to          |  logout     |            |            |
+|                      |  /FrontPage           |             |            |            |
++----------------------+-----------------------+-------------+------------+------------+
 
 .. [1] This is the default view for a Page context
        when there is no view name.
diff --git a/docs/tutorials/wiki2/installation.rst b/docs/tutorials/wiki2/installation.rst
index e5d2a0b5b..ae1396c87 100644
--- a/docs/tutorials/wiki2/installation.rst
+++ b/docs/tutorials/wiki2/installation.rst
@@ -96,9 +96,9 @@ On Windows:
 Success executing this command will end with a line to the console something
 like::
 
-   Please run the "populate_tutorial" script to set up the SQL 
+   Please run the "initialize_tutorial_db" script to set up the SQL 
    database before starting the application (e.g. 
-   "$myvirtualenv/bin/populate_tutorial development.ini".)
+   "$myvirtualenv/bin/initialize_tutorial_db development.ini".)
 
 Installing the Project in "Development Mode"
 ============================================
@@ -242,8 +242,8 @@ If successful, you will see something like this on your console::
 
 This means the server is ready to accept requests.
 
-Populating the Database
-=======================
+Initializing the Database
+=========================
 
 In a web browser, visit ``http://localhost:6543/``. 
 
@@ -255,9 +255,9 @@ You will see an error page with a title something like this::
 
 Oh no!  Something isn't working!
 
-This happens because we haven't populated the SQL database with any table
-information yet.  We need to use the ``populate_tutorial`` :term:`console
-script` to populate our database before we can see the page render correctly.
+This happens because we haven't initialized the SQL database with any table
+information yet.  We need to use the ``initialize_tutorial_db`` :term:`console
+script` to initialize our database before we can see the page render correctly.
 
 Stop the running Pyramid application by pressing ``ctrl-C`` in the console.
 Make sure you're still in the ``tutorial`` directory (the directory with a
@@ -267,13 +267,13 @@ On UNIX:
 
 .. code-block:: text
 
-   $ ../bin/populate_tutorial development.ini
+   $ ../bin/initialize_tutorial_db development.ini
 
 On Windows:
 
 .. code-block:: text
 
-   c:\pyramidtut\tutorial> ..\Scripts\populate_tutorial development.ini
+   c:\pyramidtut\tutorial> ..\Scripts\initialize_tutorial_db development.ini
 
 The output to your console should be something like this::
 
diff --git a/docs/tutorials/wiki2/src/authorization/setup.py b/docs/tutorials/wiki2/src/authorization/setup.py
index 964e39010..2fd051927 100644
--- a/docs/tutorials/wiki2/src/authorization/setup.py
+++ b/docs/tutorials/wiki2/src/authorization/setup.py
@@ -40,6 +40,6 @@ setup(name='tutorial',
       [paste.app_factory]
       main = tutorial:main
       [console_scripts]
-      populate_tutorial = tutorial.scripts.populate:main
+      initialize_tutorial_db = tutorial.scripts.initializedb:main
       """,
       )
diff --git a/docs/tutorials/wiki2/src/models/tutorial/scripts/populate.py b/docs/tutorials/wiki2/src/authorization/tutorial/scripts/initializedb.py
index 03188e8ad..03188e8ad 100644
--- a/docs/tutorials/wiki2/src/models/tutorial/scripts/populate.py
+++ b/docs/tutorials/wiki2/src/authorization/tutorial/scripts/initializedb.py
diff --git a/docs/tutorials/wiki2/src/basiclayout/setup.py b/docs/tutorials/wiki2/src/basiclayout/setup.py
index fae1c25a8..050de7299 100644
--- a/docs/tutorials/wiki2/src/basiclayout/setup.py
+++ b/docs/tutorials/wiki2/src/basiclayout/setup.py
@@ -39,7 +39,7 @@ setup(name='tutorial',
       [paste.app_factory]
       main = tutorial:main
       [console_scripts]
-      populate_tutorial = tutorial.scripts.populate:main
+      initialize_tutorial_db = tutorial.scripts.initializedb:main
       """,
       )
 
diff --git a/docs/tutorials/wiki2/src/basiclayout/tutorial/scripts/populate.py b/docs/tutorials/wiki2/src/basiclayout/tutorial/scripts/initializedb.py
index 0e828465f..0e828465f 100644
--- a/docs/tutorials/wiki2/src/basiclayout/tutorial/scripts/populate.py
+++ b/docs/tutorials/wiki2/src/basiclayout/tutorial/scripts/initializedb.py
diff --git a/docs/tutorials/wiki2/src/models/setup.py b/docs/tutorials/wiki2/src/models/setup.py
index fae1c25a8..050de7299 100644
--- a/docs/tutorials/wiki2/src/models/setup.py
+++ b/docs/tutorials/wiki2/src/models/setup.py
@@ -39,7 +39,7 @@ setup(name='tutorial',
       [paste.app_factory]
       main = tutorial:main
       [console_scripts]
-      populate_tutorial = tutorial.scripts.populate:main
+      initialize_tutorial_db = tutorial.scripts.initializedb:main
       """,
       )
 
diff --git a/docs/tutorials/wiki2/src/views/tutorial/scripts/populate.py b/docs/tutorials/wiki2/src/models/tutorial/scripts/initializedb.py
index 03188e8ad..03188e8ad 100644
--- a/docs/tutorials/wiki2/src/views/tutorial/scripts/populate.py
+++ b/docs/tutorials/wiki2/src/models/tutorial/scripts/initializedb.py
diff --git a/docs/tutorials/wiki2/src/tests/setup.py b/docs/tutorials/wiki2/src/tests/setup.py
index d05495fbd..0f58d8a18 100644
--- a/docs/tutorials/wiki2/src/tests/setup.py
+++ b/docs/tutorials/wiki2/src/tests/setup.py
@@ -41,6 +41,6 @@ setup(name='tutorial',
       [paste.app_factory]
       main = tutorial:main
       [console_scripts]
-      populate_tutorial = tutorial.scripts.populate:main
+      initialize_tutorial_db = tutorial.scripts.initializedb:main
       """,
       )
diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/scripts/populate.py b/docs/tutorials/wiki2/src/tests/tutorial/scripts/initializedb.py
index 981adff38..03188e8ad 100644
--- a/docs/tutorials/wiki2/src/authorization/tutorial/scripts/populate.py
+++ b/docs/tutorials/wiki2/src/tests/tutorial/scripts/initializedb.py
@@ -21,7 +21,7 @@ def usage(argv):
           '(example: "%s development.ini")' % (cmd, cmd)) 
     sys.exit(1)
 
-def main(argv=sys.argv, settings=None):
+def main(argv=sys.argv):
     if len(argv) != 2:
         usage(argv)
     config_uri = argv[1]
diff --git a/docs/tutorials/wiki2/src/tests/tutorial/scripts/populate.py b/docs/tutorials/wiki2/src/tests/tutorial/scripts/populate.py
deleted file mode 100644
index de74f4d63..000000000
--- a/docs/tutorials/wiki2/src/tests/tutorial/scripts/populate.py
+++ /dev/null
@@ -1,36 +0,0 @@
-import os
-import sys
-import transaction
-
-from sqlalchemy import engine_from_config
-
-from pyramid.paster import (
-    get_appsettings,
-    setup_logging,
-    )
-
-from ..models import (
-    DBSession,
-    Page,
-    Base,
-    )
-
-def usage(argv):
-    cmd = os.path.basename(argv[0])
-    print('usage: %s <config_uri>\n'
-          '(example: "%s development.ini")' % (cmd, cmd)) 
-    sys.exit(1)
-
-def main(argv=sys.argv, settings=None):
-    if len(argv) != 2:
-        usage(argv)
-    config_uri = argv[1]
-    if settings is None:
-        setup_logging(config_uri)
-        settings = get_appsettings(config_uri)
-    engine = engine_from_config(settings, 'sqlalchemy.')
-    DBSession.configure(bind=engine)
-    Base.metadata.create_all(engine)
-    with transaction.manager:
-        model = Page('FrontPage', 'This is the front page')
-        DBSession.add(model)
diff --git a/docs/tutorials/wiki2/src/tests/tutorial/tests.py b/docs/tutorials/wiki2/src/tests/tutorial/tests.py
index 557d1b1be..c7b7d884b 100644
--- a/docs/tutorials/wiki2/src/tests/tutorial/tests.py
+++ b/docs/tutorials/wiki2/src/tests/tutorial/tests.py
@@ -246,23 +246,3 @@ class FunctionalTests(unittest.TestCase):
         self.testapp.get(self.editor_login, status=302)
         res = self.testapp.get('/FrontPage', status=200)
         self.assertTrue('FrontPage' in res.body)
-
-class Test_populate(unittest.TestCase):
-    def setUp(self):
-        from tutorial.models import DBSession
-        DBSession.remove()
-
-    def tearDown(self):
-        from tutorial.models import DBSession
-        DBSession.remove()
-
-    def _callFUT(self, settings):
-        from tutorial.scripts.populate import main
-        main(['foo', 'development.ini'], settings)
-
-    def test_it(self):
-        self._callFUT({'sqlalchemy.url':'sqlite://'})
-        from tutorial.models import DBSession, Page
-        self.assertEqual(DBSession.query(Page).one().data,
-            'This is the front page')
-
diff --git a/docs/tutorials/wiki2/src/views/setup.py b/docs/tutorials/wiki2/src/views/setup.py
index 834280118..34b578e21 100644
--- a/docs/tutorials/wiki2/src/views/setup.py
+++ b/docs/tutorials/wiki2/src/views/setup.py
@@ -40,7 +40,7 @@ setup(name='tutorial',
       [paste.app_factory]
       main = tutorial:main
       [console_scripts]
-      populate_tutorial = tutorial.scripts.populate:main
+      initialize_tutorial_db = tutorial.scripts.initializedb:main
       """,
       )
 
diff --git a/docs/tutorials/wiki2/src/views/tutorial/scripts/initializedb.py b/docs/tutorials/wiki2/src/views/tutorial/scripts/initializedb.py
new file mode 100644
index 000000000..03188e8ad
--- /dev/null
+++ b/docs/tutorials/wiki2/src/views/tutorial/scripts/initializedb.py
@@ -0,0 +1,35 @@
+import os
+import sys
+import transaction
+
+from sqlalchemy import engine_from_config
+
+from pyramid.paster import (
+    get_appsettings,
+    setup_logging,
+    )
+
+from ..models import (
+    DBSession,
+    Page,
+    Base,
+    )
+
+def usage(argv):
+    cmd = os.path.basename(argv[0])
+    print('usage: %s <config_uri>\n'
+          '(example: "%s development.ini")' % (cmd, cmd)) 
+    sys.exit(1)
+
+def main(argv=sys.argv):
+    if len(argv) != 2:
+        usage(argv)
+    config_uri = argv[1]
+    setup_logging(config_uri)
+    settings = get_appsettings(config_uri)
+    engine = engine_from_config(settings, 'sqlalchemy.')
+    DBSession.configure(bind=engine)
+    Base.metadata.create_all(engine)
+    with transaction.manager:
+        model = Page('FrontPage', 'This is the front page')
+        DBSession.add(model)
diff --git a/docs/tutorials/wiki2/tests.rst b/docs/tutorials/wiki2/tests.rst
index 94d97d2d5..86880fb18 100644
--- a/docs/tutorials/wiki2/tests.rst
+++ b/docs/tutorials/wiki2/tests.rst
@@ -13,9 +13,8 @@ We write a test class for the model class ``Page`` and another test class
 for the ``initialize_sql`` function.
 
 To do so, we'll retain the ``tutorial.tests.ViewTests`` class provided as a
-result of the ``alchemy`` scaffold.  We'll add two test classes: one for the
-``Page`` model named ``PageModelTests``, and one for the ``populate`` script
-named ``Test_populate``.
+result of the ``alchemy`` scaffold.  We'll add a test class named
+``PageModelTests`` for the ``Page`` model.
 
 Testing the Views
 =================
@@ -34,18 +33,6 @@ tested in the unit tests, like logging in, logging out, checking that
 the ``viewer`` user cannot add or edit pages, but the ``editor`` user
 can, and so on.
 
-We must first modify ``main()`` in ``scripts/populate.py``, adding an
-optional ``settings`` argument so we can pass in a URI to a
-memory-resident database instead of our disk-based database we've
-populated; this allows us to run our tests with a clean database each
-time.  Replace ``main()`` with this version which adds an argument and
-then uses it if set, and creates a ``Model`` for testing:
-
-.. literalinclude:: src/tests/tutorial/scripts/populate.py
-   :lines: 24-36
-   :linenos:
-   :language: python
-
 Viewing the results of all our edits to ``tests.py``
 ====================================================