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 ++++++++++++---------- 7 files changed, 20 insertions(+), 16 deletions(-) (limited to 'docs/narr') 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 -- cgit v1.2.3