From f2520e5910861beac0199aa424ba282f856f79b3 Mon Sep 17 00:00:00 2001 From: Stephen Martin Date: Sun, 16 Sep 2018 15:46:31 -0700 Subject: doc fixes --- docs/narr/advanced-features.rst | 2 +- docs/narr/assets.rst | 2 +- docs/narr/commandline.rst | 2 +- docs/narr/cookiecutters.rst | 4 +++- docs/narr/install.rst | 2 +- docs/narr/logging.rst | 2 +- docs/narr/project.rst | 22 ++++++++++++---------- docs/quick_tutorial/cookiecutters.rst | 13 +------------ docs/quick_tutorial/databases.rst | 8 ++++---- docs/tutorials/wiki/basiclayout.rst | 8 ++++---- docs/tutorials/wiki/definingviews.rst | 4 ++-- docs/tutorials/wiki/installation.rst | 7 +++---- docs/tutorials/wiki/tests.rst | 4 ++-- docs/tutorials/wiki2/basiclayout.rst | 7 ++++--- docs/tutorials/wiki2/definingviews.rst | 10 +++++----- docs/tutorials/wiki2/installation.rst | 8 ++++---- docs/tutorials/wiki2/tests.rst | 4 ++-- 17 files changed, 51 insertions(+), 58 deletions(-) (limited to 'docs') diff --git a/docs/narr/advanced-features.rst b/docs/narr/advanced-features.rst index 71985e49c..b169aad95 100644 --- a/docs/narr/advanced-features.rst +++ b/docs/narr/advanced-features.rst @@ -51,7 +51,7 @@ This approach allows you to develop view code that is simpler, more easily under Stop Worrying About Transactions -------------------------------- -:app:`Pyramid`\ 's :term:`cookiecutter`\ renders projects that include a *transaction management* system. When you use this system, you can stop worrying about when to commit your changes, :app:`Pyramid` handles it for you. The system will commit at the end of a request or abort if there was an exception. +:app:`Pyramid`\ 's :term:`cookiecutter` renders projects that include a *transaction management* system. When you use this system, you can stop worrying about when to commit your changes, :app:`Pyramid` handles it for you. The system will commit at the end of a request or abort if there was an exception. Why is that a good thing? Imagine a situation where you manually commit a change to your persistence layer. It's very likely that other framework code will run *after* your changes are done. If an error happens in that other code, you can easily wind up with inconsistent data if you're not extremely careful. diff --git a/docs/narr/assets.rst b/docs/narr/assets.rst index 811285039..06594dbb7 100644 --- a/docs/narr/assets.rst +++ b/docs/narr/assets.rst @@ -27,7 +27,7 @@ asset: package. The use of assets is quite common in most web development projects. For -example, when you create a :app:`Pyramid` application using our +example, when you create a :app:`Pyramid` application using the :term:`cookiecutter`, as described in :ref:`creating_a_project`, the directory representing the application contains a Python :term:`package`. Within that Python package, there are directories full of files which are static assets. diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index 70c86bcac..f8ca8366b 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -298,7 +298,7 @@ By defining the ``setup`` callable, we will create the module ``myapp.lib.pshell # start a transaction which can be used in the shell request.tm.begin() - # if using the alchemy backend to our cookiecutter, the dbsession is + # if using the SQLAlchemy backend from our cookiecutter, the dbsession is # connected to the transaction manager above env['tm'] = request.tm env['dbsession'] = request.dbsession diff --git a/docs/narr/cookiecutters.rst b/docs/narr/cookiecutters.rst index 4c10229a6..f46fc5882 100644 --- a/docs/narr/cookiecutters.rst +++ b/docs/narr/cookiecutters.rst @@ -3,10 +3,12 @@ Pyramid cookiecutters ===================== -.. versionadded:: 1.8 +.. versionadded:: 1.10 A :term:`cookiecutter` is a command-line utility that creates projects from :ref:`cookiecutters ` (project templates), e.g., creating a Python package project from a Python package project template. +The unified cookiecutter ``pyramid-cookiecutter-theonecc`` merged features from the three previous cookiecutters which are now deprecated. + The Pyramid cookiecutter has replaced the now deprecated Pyramid scaffolds, and should be used going forward and can be found here: * `pyramid-cookiecutter-theonecc `_ diff --git a/docs/narr/install.rst b/docs/narr/install.rst index b70f43937..dbf5dc2eb 100644 --- a/docs/narr/install.rst +++ b/docs/narr/install.rst @@ -262,4 +262,4 @@ What Gets Installed When you install :app:`Pyramid`, various libraries such as WebOb, PasteDeploy, and others are installed. -Additionally, as chronicled in :ref:`project_narr`, our :term:`cookiecutter` will be used, which make it easy to start a new :app:`Pyramid` project. +Additionally, as chronicled in :ref:`project_narr`, our :term:`cookiecutter` will be used, which makes it easy to start a new :app:`Pyramid` project. diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst index c3da1e920..7b60beda9 100644 --- a/docs/narr/logging.rst +++ b/docs/narr/logging.rst @@ -89,7 +89,7 @@ root logger level to ``DEBUG`` reveals them: handlers = console Some configurations of the :app:`Pyramid` cookiecutter configure additional loggers for -additional subsystems they use (such as SQLALchemy). Take a look at the +additional subsystems they use (such as SQLAlchemy). Take a look at the ``production.ini`` and ``development.ini`` files rendered when you create a project from our cookiecutter. diff --git a/docs/narr/project.rst b/docs/narr/project.rst index f016df7be..e0d511fba 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -17,7 +17,7 @@ also be distributed more easily than one which does not live within a package. The Pylons Project provides a :app:`Pyramid` cookiecutter that you can use to generate a project. Our cookiecutter allows several configuration options -to layout what type of application you're trying to construct. +to generate the type of application you're trying to construct. This cookiecutter is rendered using the ``cookiecutter`` command that you may install. @@ -35,25 +35,27 @@ This cookiecutter is rendered using the ``cookiecutter`` command that you may in :app:`Pyramid` cookiecutters ---------------------------- -The Pyramid cookiecutter released under the Pylons Project differ in configuration options on a number of axes: +The Pyramid cookiecutter released under the Pylons Project offers the following configuration options: -- the persistence mechanism it offers (no persistence mechanism, :term:`SQLAlchemy` with SQLite, or :term:`ZODB`) +- templating libraries (:term:`Jinja2`, :term:`Chameleon`, or :term:`Mako`) -- the mechanism it uses to map URLs to code (:term:`URL dispatch` or :term:`traversal`) +- the persistence mechanism (no persistence mechanism, :term:`SQLAlchemy` with SQLite, or :term:`ZODB`) -- All include an option of templating libraries (:term:`Jinja2`, :term:`Chameleon`, or :term:`Mako`) +- the mechanism of mapping URLs to code (:term:`URL dispatch` or :term:`traversal`) * `pyramid-cookiecutter-theonecc `_ -These configurations include: +All configuration options offer a choice of templating language. -``no persistance`` +The configuration of mapping URLs to code (routing) depends on the backend option selected, with additional variations as follows. + +``none`` :term:`URL dispatch` for routing -``SQLAlchemy`` - SQLite for persistent storage, :term:`SQLAlchemy` for an ORM, and :term:`URL dispatch` for routing +``sqlalchemy`` + SQLite for persistent storage, :term:`SQLAlchemy` for an ORM, :term:`URL dispatch` for routing, and :term:`Alembic` for database migrations -``ZODB`` +``zodb`` :term:`ZODB` for persistent storage and :term:`traversal` for routing diff --git a/docs/quick_tutorial/cookiecutters.rst b/docs/quick_tutorial/cookiecutters.rst index dee301a12..9734c36bc 100644 --- a/docs/quick_tutorial/cookiecutters.rst +++ b/docs/quick_tutorial/cookiecutters.rst @@ -4,7 +4,7 @@ Prelude: Quick Project Startup with Cookiecutters ================================================= -To ease the process of getting started on a project, the Pylons Project provides :term:`cookiecutter`\ s that generate sample :app:`Pyramid` projects from project templates. These cookiecutters will install :app:`Pyramid` and its dependencies as well. We will still cover many topics of web application development using :app:`Pyramid`, but it's good to know of this facility. This prelude will demonstrate how to get a working :app:`Pyramid` web application running via ``cookiecutter``. +To ease the process of getting started on a project, the Pylons Project provides a :term:`cookiecutter` that generates sample :app:`Pyramid` projects from project templates. The cookiecutter will install :app:`Pyramid` and its dependencies as well. We will still cover many topics of web application development using :app:`Pyramid`, but it's good to know of this facility. This prelude will demonstrate how to get a working :app:`Pyramid` web application running via ``cookiecutter``. Objectives @@ -62,17 +62,6 @@ Steps # ...and into which we install our project. env/bin/pip install -e . - **Note:** If you selected ``sqlalchemy`` in the preceding step, continue. Otherwise, skip to the next step. - - .. code-block:: bash - - # Generate your first revision. - env/bin/alembic -c development.ini revision --autogenerate -m "init" - # Upgrade to that revision. - env/bin/alembic -c development.ini upgrade head - # Load default data. - env/bin/initialize_cc_starter_db development.ini - #. Start up the application by pointing :app:`Pyramid`'s ``pserve`` command at the project's (generated) configuration file: diff --git a/docs/quick_tutorial/databases.rst b/docs/quick_tutorial/databases.rst index 7d28f4ba2..3082dc4d2 100644 --- a/docs/quick_tutorial/databases.rst +++ b/docs/quick_tutorial/databases.rst @@ -21,10 +21,10 @@ storage and retrieval for the wiki pages in the previous step. .. note:: - The Pyramid cookiecutter is really helpful for getting an SQLAlchemy - project going, including generation of the console script. Since we want to - see all the decisions, we will forgo convenience in this tutorial, and wire - it up ourselves. + The Pyramid cookiecutter ``pyramid-cookiecutter-theonecc`` is really + helpful for getting a SQLAlchemy project going, including generation of + the console script. Since we want to see all the decisions, we will forgo + convenience in this tutorial, and wire it up ourselves. Objectives diff --git a/docs/tutorials/wiki/basiclayout.rst b/docs/tutorials/wiki/basiclayout.rst index d435e0767..0005ba3cb 100644 --- a/docs/tutorials/wiki/basiclayout.rst +++ b/docs/tutorials/wiki/basiclayout.rst @@ -4,10 +4,10 @@ Basic Layout ============ -The starter files generated by the ``zodb`` backend cookiecutter are very -basic, but they provide a good orientation for the high-level patterns common -to most :term:`traversal`-based (and :term:`ZODB`-based) :app:`Pyramid` -projects. +The starter files generated by selecting the ``zodb`` backend in the +cookiecutter are very basic, but they provide a good orientation for the +high-level patterns common to most :term:`traversal`-based (and +:term:`ZODB`-based) :app:`Pyramid` projects. Application configuration with ``__init__.py`` diff --git a/docs/tutorials/wiki/definingviews.rst b/docs/tutorials/wiki/definingviews.rst index 91b90e911..d584a1b41 100644 --- a/docs/tutorials/wiki/definingviews.rst +++ b/docs/tutorials/wiki/definingviews.rst @@ -99,8 +99,8 @@ like the following: We added some imports and created a regular expression to find "WikiWords". We got rid of the ``my_view`` view function and its decorator that was added -when we originally rendered the ``zodb`` backend cookiecutter. It was only an example and -isn't relevant to our application. +when originally rendered after we selected the ``zodb`` backend option in the +cookiecutter. It was only an example and isn't relevant to our application. Then we added four :term:`view callable` functions to our ``views.py`` module: diff --git a/docs/tutorials/wiki/installation.rst b/docs/tutorials/wiki/installation.rst index c7047664a..bd8ea9e5c 100644 --- a/docs/tutorials/wiki/installation.rst +++ b/docs/tutorials/wiki/installation.rst @@ -365,11 +365,10 @@ page. You can read more about the purpose of the icon at application while you develop. -Decisions the ``zodb`` backend cookiecutter has made for you ------------------------------------------------------------- +Decisions the cookiecutter backend option ``zodb`` has made for you +------------------------------------------------------------------- -Creating a project using the ``zodb`` backend cookiecutter makes the following -assumptions: +When creating a project and selecting the backend option of ``zodb``, the cookiecutter makes the following assumptions: - You are willing to use :term:`ZODB` for persistent storage. diff --git a/docs/tutorials/wiki/tests.rst b/docs/tutorials/wiki/tests.rst index 81b020594..353813e91 100644 --- a/docs/tutorials/wiki/tests.rst +++ b/docs/tutorials/wiki/tests.rst @@ -16,7 +16,7 @@ We write tests for the ``model`` classes and the ``appmaker``. Changing we'll write a test class for the ``appmaker``. To do so, we'll retain the ``tutorial.tests.ViewTests`` class that was -generated as part of the ``zodb`` backend cookiecutter. We'll add three test +generated from choosing the ``zodb`` backend option. We'll add three test classes: one for the ``Page`` model named ``PageModelTests``, one for the ``Wiki`` model named ``WikiModelTests``, and one for the appmaker named ``AppmakerTests``. @@ -26,7 +26,7 @@ Test the views We'll modify our ``tests.py`` file, adding tests for each view function we added previously. As a result, we'll delete the ``ViewTests`` class that the -``zodb`` backend cookiecutter provided, and add four other test classes: +``zodb`` backend option provided, and add four other test classes: ``ViewWikiTests``, ``ViewPageTests``, ``AddPageTests``, and ``EditPageTests``. These test the ``view_wiki``, ``view_page``, ``add_page``, and ``edit_page`` views. diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index bb2d4cdcf..f3a9db223 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -4,9 +4,10 @@ Basic Layout ============ -The starter files generated by the ``sqlalchemy`` backend cookiecutter are very -basic, but they provide a good orientation for the high-level patterns common -to most :term:`URL dispatch`-based :app:`Pyramid` projects. +The starter files generated from choosing the ``sqlalchemy`` backend option in +the cookiecutter are very basic, but they provide a good orientation for the +high-level patterns common to most :term:`URL dispatch`-based :app:`Pyramid` +projects. Application configuration with ``__init__.py`` diff --git a/docs/tutorials/wiki2/definingviews.rst b/docs/tutorials/wiki2/definingviews.rst index c75f6d5ba..b73338f52 100644 --- a/docs/tutorials/wiki2/definingviews.rst +++ b/docs/tutorials/wiki2/definingviews.rst @@ -133,9 +133,9 @@ The highlighted lines need to be added or edited. We added some imports, and created a regular expression to find "WikiWords". We got rid of the ``my_view`` view function and its decorator that was added -when we originally rendered the ``sqlalchemy`` backend cookiecutter. It was -only an example and isn't relevant to our application. We also deleted the -``db_err_msg`` string. +when originally rendered after we selected the ``sqlalchemy`` backend option in +the cookiecutter. It was only an example and isn't relevant to our +application. We also deleted the ``db_err_msg`` string. Then we added four :term:`view callable` functions to our ``views/default.py`` module, as mentioned in the previous step: @@ -436,8 +436,8 @@ There are several important things to note about this configuration: the view. Finally, we may delete the ``tutorial/templates/mytemplate.jinja2`` template -that was provided by the ``sqlalchemy`` backend cookiecutter, as we have -created our own templates for the wiki. +that was provided by selecting the backend option of ``sqlalchemy``, as we +have created our own templates for the wiki. .. note:: diff --git a/docs/tutorials/wiki2/installation.rst b/docs/tutorials/wiki2/installation.rst index 133bf75d3..0ab097b59 100644 --- a/docs/tutorials/wiki2/installation.rst +++ b/docs/tutorials/wiki2/installation.rst @@ -519,11 +519,11 @@ page. You can read more about the purpose of the icon at application while you develop. -Decisions the ``sqlalchemy`` backend cookiecutter has made for you ------------------------------------------------------------------- +Decisions the cookiecutter backend option ``sqlalchemy`` has made for you +------------------------------------------------------------------------- -Creating a project using the ``sqlalchemy`` cookiecutter makes the following -assumptions: +When creating a project and selecting the backend option of ``sqlalchemy``, the +cookiecutter makes the following assumptions: - You are willing to use SQLite for persistent storage, although almost any SQL database could be used with SQLAlchemy. diff --git a/docs/tutorials/wiki2/tests.rst b/docs/tutorials/wiki2/tests.rst index 99a594d31..a8c35aa51 100644 --- a/docs/tutorials/wiki2/tests.rst +++ b/docs/tutorials/wiki2/tests.rst @@ -8,8 +8,8 @@ We will now add tests for the models and views as well as a few functional tests in a new ``tests`` subpackage. Tests ensure that an application works, and that it continues to work when changes are made in the future. -The file ``tests.py`` was generated as part of the ``sqlalchemy`` backend -cookiecutter, but it is a common practice to put tests into a ``tests`` +The file ``tests.py`` was generated from choosing the ``sqlalchemy`` backend +option, but it is a common practice to put tests into a ``tests`` subpackage, especially as projects grow in size and complexity. Each module in the test subpackage should contain tests for its corresponding module in our application. Each corresponding pair of modules should have the same names, -- cgit v1.2.3