From 6b6d0e4c2b4e56523bd41aefd9d462858e03f443 Mon Sep 17 00:00:00 2001 From: Stephen Martin Date: Sun, 9 Sep 2018 17:05:27 -0700 Subject: merging cookiecutters --- docs/narr/advanced-features.rst | 4 +-- docs/narr/assets.rst | 4 +-- docs/narr/commandline.rst | 4 +-- docs/narr/cookiecutters.rst | 6 ++-- docs/narr/extending.rst | 2 +- docs/narr/install.rst | 3 +- docs/narr/introduction.rst | 2 +- docs/narr/logging.rst | 21 ++++++------ docs/narr/paste.rst | 4 +-- docs/narr/project.rst | 73 +++++++++++++++++++++-------------------- docs/narr/scaffolding.rst | 2 +- docs/narr/webob.rst | 2 +- 12 files changed, 64 insertions(+), 63 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/advanced-features.rst b/docs/narr/advanced-features.rst index 191996c27..71985e49c 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`\ s render 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. @@ -327,4 +327,4 @@ Here's an example of using :app:`Pyramid`\ 's :term:`introspector` from within a .. seealso:: - See also :ref:`using_introspection`. \ No newline at end of file + See also :ref:`using_introspection`. diff --git a/docs/narr/assets.rst b/docs/narr/assets.rst index 2b0b90b4a..811285039 100644 --- a/docs/narr/assets.rst +++ b/docs/narr/assets.rst @@ -27,8 +27,8 @@ asset: package. The use of assets is quite common in most web development projects. For -example, when you create a :app:`Pyramid` application using one of the -available :term:`cookiecutter`\ s, as described in :ref:`creating_a_project`, the directory +example, when you create a :app:`Pyramid` application using our +: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. For example, there's a ``static`` directory which contains ``.css``, ``.js``, diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index 98e34fea2..70c86bcac 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -298,8 +298,8 @@ 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 cookiecutter, the dbsession is connected - # to the transaction manager above + # if using the alchemy backend to our cookiecutter, the dbsession is + # connected to the transaction manager above env['tm'] = request.tm env['dbsession'] = request.dbsession try: diff --git a/docs/narr/cookiecutters.rst b/docs/narr/cookiecutters.rst index abedb25b9..4c10229a6 100644 --- a/docs/narr/cookiecutters.rst +++ b/docs/narr/cookiecutters.rst @@ -7,11 +7,9 @@ Pyramid cookiecutters 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. -Pyramid cookiecutters have replaced the now deprecated Pyramid scaffolds, and should be used going forward. Pyramid cookiecutters released under the Pylons Project include: +The Pyramid cookiecutter has replaced the now deprecated Pyramid scaffolds, and should be used going forward and can be found here: -* `pyramid-cookiecutter-alchemy `_ -* `pyramid-cookiecutter-starter `_ -* `pyramid-cookiecutter-zodb `_ +* `pyramid-cookiecutter-theonecc `_ .. seealso:: diff --git a/docs/narr/extending.rst b/docs/narr/extending.rst index 1a6804792..ccf871ca8 100644 --- a/docs/narr/extending.rst +++ b/docs/narr/extending.rst @@ -190,7 +190,7 @@ The general pattern for extending an existing application looks something like this: - Create a new Python package. The easiest way to do this is to create a new - :app:`Pyramid` application using a :term:`cookiecutter`. See + :app:`Pyramid` application using our :term:`cookiecutter`. See :ref:`creating_a_project` for more information. - In the new package, create Python files containing views and other overridden diff --git a/docs/narr/install.rst b/docs/narr/install.rst index 743cb4abb..b70f43937 100644 --- a/docs/narr/install.rst +++ b/docs/narr/install.rst @@ -262,5 +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`, :term:`cookiecutter`\ s 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 make it easy to start a new :app:`Pyramid` project. diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst index 3ee6b5367..cc1ecdbee 100644 --- a/docs/narr/introduction.rst +++ b/docs/narr/introduction.rst @@ -144,7 +144,7 @@ Develop interactively When your application has an error, an interactive debugger allows you to poke around from your browser to find out what happened. -To use the :app:`Pyramid` debug toolbar, build your project with a :app:`Pyramid` :term:`cookiecutter`. +To use the :app:`Pyramid` debug toolbar, build your project with our :term:`cookiecutter`. .. seealso:: diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst index ce83cd3ee..c3da1e920 100644 --- a/docs/narr/logging.rst +++ b/docs/narr/logging.rst @@ -9,10 +9,10 @@ to send log messages to loggers that you've configured. .. warning:: - This chapter assumes you've used a :term:`cookiecutter` to create a project + This chapter assumes you've used our :term:`cookiecutter` to create a project which contains ``development.ini`` and ``production.ini`` files which help - configure logging. All of the Pyramid cookiecutters provided by the Pylons Project do - this. If you're not using a cookiecutter, or if you've used a third-party + configure logging. The Pyramid cookiecutter provided by the Pylons Project does + this. If you're not using our cookiecutter, or if you've used a third-party cookiecutter which does not create these files, the configuration information in this chapter may not be applicable. @@ -26,11 +26,11 @@ to send log messages to loggers that you've configured. Logging Configuration --------------------- -A :app:`Pyramid` project created from a :term:`cookiecutter` is configured to allow +A :app:`Pyramid` project created from our :term:`cookiecutter` is configured to allow you to send messages to :mod:`Python standard library logging package ` loggers from within your application. In particular, the :term:`PasteDeploy` ``development.ini`` and ``production.ini`` files created -when you use a cookiecutter include a basic configuration for the Python +when you use our cookiecutter include a basic configuration for the Python :mod:`logging` package. PasteDeploy ``.ini`` files use the Python standard library :mod:`ConfigParser @@ -47,7 +47,7 @@ cookiecutter-generated ``.ini`` files do). ``setup_logging`` reads the logging configuration from the ini file upon which ``pserve`` was invoked. Default logging configuration is provided in both the default -``development.ini`` and the ``production.ini`` files. If you use ``pyramid-cookiecutter-starter`` to generate a Pyramid project with the name of the package as ``hello_world``, then the logging configuration +``development.ini`` and the ``production.ini`` files. If you use our cookiecutter to generate a Pyramid project with the name of the package as ``hello_world``, then the logging configuration in the ``development.ini`` file is as follows: .. literalinclude:: myproject/development.ini @@ -75,7 +75,7 @@ that ask for a logger (via ``logging.getLogger``) that has a name which begins with anything except your project's package name (e.g., ``myproject``). The logger with the same name as your package name is reserved for your own usage in your :app:`Pyramid` application. Its existence means that you can log to a known -logging location from any :app:`Pyramid` application generated via a cookiecutter. +logging location from any :app:`Pyramid` application generated via our cookiecutter. :app:`Pyramid` and many other libraries (such as Beaker, SQLAlchemy, Paste) log a number of messages to the root logger for debugging purposes. Switching the @@ -88,9 +88,10 @@ root logger level to ``DEBUG`` reveals them: level = DEBUG handlers = console -Some cookiecutters configure additional loggers for 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 a cookiecutter. +Some configurations of the :app:`Pyramid` cookiecutter configure additional loggers for +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. Sending Logging Messages ------------------------ diff --git a/docs/narr/paste.rst b/docs/narr/paste.rst index c02036f69..8a0d505b3 100644 --- a/docs/narr/paste.rst +++ b/docs/narr/paste.rst @@ -14,7 +14,7 @@ runner ``pserve``, as well as other commands such as ``pviews``, ``pshell``, PasteDeploy is not a particularly integral part of Pyramid. It's possible to create a Pyramid application which does not use PasteDeploy at all. We show a Pyramid application that doesn't use PasteDeploy in :ref:`firstapp_chapter`. -However, all Pyramid cookiecutters render PasteDeploy configuration files, to +However, the Pyramid cookiecutter renders PasteDeploy configuration files, to provide new developers with a standardized way of setting deployment values, and to provide new users with a standardized way of starting, stopping, and debugging an application. @@ -75,7 +75,7 @@ In English, this entry point can thus be referred to as a "PasteDeploy application factory in the ``myproject`` project which has the entry point named ``main`` where the entry point refers to a ``main`` function in the ``mypackage`` module". Indeed, if you open up the ``__init__.py`` module -generated within any cookiecutter-generated package, you'll see a ``main`` +generated within the cookiecutter-generated package, you'll see a ``main`` function. This is the function called by :term:`PasteDeploy` when the ``pserve`` command is invoked against our application. It accepts a global configuration object and *returns* an instance of our application. diff --git a/docs/narr/project.rst b/docs/narr/project.rst index fb5a241db..f016df7be 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -5,21 +5,21 @@ Creating a :app:`Pyramid` Project As we saw in :ref:`firstapp_chapter`, it's possible to create a :app:`Pyramid` application completely manually. However, it's usually more convenient to use -a :term:`cookiecutter` to generate a basic :app:`Pyramid` :term:`project`. +our :term:`cookiecutter` to generate a basic :app:`Pyramid` :term:`project`. A project is a directory that contains at least one Python :term:`package`. -You'll use a cookiecutter to create a project, and you'll create your application -logic within a package that lives inside the project. Even if your application -is extremely simple, it is useful to place code that drives the application -within a package, because (1) a package is more easily extended with new code, -and (2) an application that lives inside a package can also be distributed more -easily than one which does not live within a package. +You'll use the :app:`Pyramid` cookiecutter to create a project, and you'll +create your application logic within a package that lives inside the project. +Even if your application is extremely simple, it is useful to place code that +drives the application within a package, because (1) a package is more easily +extended with new code, and (2) an application that lives inside a package can +also be distributed more easily than one which does not live within a package. -The Pylons Project provides several :app:`Pyramid` cookiecutters that you can use to generate a -project. Each cookiecutter makes different configuration assumptions about what -type of application you're trying to construct. +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. -These cookiecutters are rendered using the ``cookiecutter`` command that you may install. +This cookiecutter is rendered using the ``cookiecutter`` command that you may install. .. seealso:: @@ -28,37 +28,33 @@ These cookiecutters are rendered using the ``cookiecutter`` command that you may .. index:: single: cookiecutters - single: pyramid-cookiecutter-starter - single: pyramid-cookiecutter-zodb - single: pyramid-cookiecutter-alchemy + single: pyramid-cookiecutter-theonecc .. _additional_cookiecutters: :app:`Pyramid` cookiecutters ---------------------------- -Pyramid cookiecutters released under the Pylons Project differ from each other on a number of axes: +The Pyramid cookiecutter released under the Pylons Project differ in configuration options on a number of axes: -- the persistence mechanism they offer (no persistence mechanism, :term:`SQLAlchemy` with SQLite, or :term:`ZODB`) +- the persistence mechanism it offers (no persistence mechanism, :term:`SQLAlchemy` with SQLite, or :term:`ZODB`) -- the mechanism they use to map URLs to code (:term:`URL dispatch` or :term:`traversal`) +- the mechanism it uses to map URLs to code (:term:`URL dispatch` or :term:`traversal`) -- templating libraries (:term:`Jinja2`, :term:`Chameleon`, or :term:`Mako`) +- All include an option of templating libraries (:term:`Jinja2`, :term:`Chameleon`, or :term:`Mako`) -* `pyramid-cookiecutter-starter `_ -* `pyramid-cookiecutter-alchemy `_ -* `pyramid-cookiecutter-zodb `_ +* `pyramid-cookiecutter-theonecc `_ -These cookiecutters include: +These configurations include: -``pyramid-cookiecutter-starter`` - :term:`URL dispatch` for routing and either :term:`Jinja2`, :term:`Chameleon`, or :term:`Mako` for templating +``no persistance`` + :term:`URL dispatch` for routing -``pyramid-cookiecutter-alchemy`` - SQLite for persistent storage, :term:`SQLAlchemy` for an ORM, :term:`URL dispatch` for routing, and :term:`Jinja2` for templating. +``SQLAlchemy`` + SQLite for persistent storage, :term:`SQLAlchemy` for an ORM, and :term:`URL dispatch` for routing -``pyramid-cookiecutter-zodb`` - :term:`ZODB` for persistent storage, :term:`traversal` for routing, and :term:`Chameleon` for templating +``ZODB`` + :term:`ZODB` for persistent storage and :term:`traversal` for routing .. index:: @@ -77,7 +73,7 @@ In :ref:`installing_chapter`, you created a virtual Python environment via the We assume that you :ref:`previously installed cookiecutter `, following its installation instructions. -We'll choose ``pyramid-cookiecutter-starter`` to start the project. When we invoke ``cookiecutter``, it will create a directory that represents our project. +When we invoke ``cookiecutter``, it will create a directory that represents our project. We assume our current working directory is the value of ``VENV``. @@ -85,13 +81,13 @@ On all platforms, generate a project using cookiecutter. .. code-block:: bash - cookiecutter gh:Pylons/pyramid-cookiecutter-starter --checkout master + cookiecutter gh:Pylons/pyramid-cookiecutter-theonecc --checkout master If prompted for the first item, accept the default ``yes`` by hitting return. .. code-block:: text - You've cloned ~/.cookiecutters/pyramid-cookiecutter-starter before. + You've cloned ~/.cookiecutters/pyramid-cookiecutter-theonecc before. Is it okay to delete and re-clone it? [yes]: yes project_name [Pyramid Scaffold]: myproject repo_name [myproject]: myproject @@ -100,6 +96,11 @@ If prompted for the first item, accept the default ``yes`` by hitting return. 2 - chameleon 3 - mako Choose from 1, 2, 3 [1]: 1 + Select backend: + 1 - none + 2 - sqlalchemy + 3 - zodb + Choose from 1, 2, 3 [1]: 1 We then run through the following commands. @@ -262,7 +263,7 @@ Here's sample output from a test run on Unix: .. 2 passed in 0.47 seconds -The tests themselves are found in the ``tests.py`` module in your ``cookiecutter``-generated project. Within a project generated by the ``pyramid-cookiecutter-starter`` cookiecutter, only two sample tests exist. +The tests themselves are found in the ``tests.py`` module in your ``cookiecutter``-generated project. Within a project generated by the ``pyramid-cookiecutter-theonecc`` cookiecutter, only two sample tests exist. .. note:: @@ -434,7 +435,7 @@ browser like what is displayed in the following image: .. image:: project.png This is the page shown by default when you visit an unmodified ``cookiecutter`` -generated ``pyramid-cookiecutter-starter`` application in a browser. +generated ``pyramid-cookiecutter-theonecc`` application in a browser. .. index:: single: debug toolbar @@ -515,7 +516,7 @@ this: The Project Structure --------------------- -The ``pyramid-cookiecutter-starter`` cookiecutter generated a :term:`project` (named ``myproject``), +The ``pyramid-cookiecutter-theonecc`` cookiecutter generated a :term:`project` (named ``myproject``), which contains a Python :term:`package`. The package is *also* named ``myproject``; the cookiecutter generates a project which contains a package that shares its name. @@ -818,6 +819,8 @@ The ``myproject`` :term:`package` lives inside the ``myproject`` #. A ``tests.py`` module, which contains unit test code for the application. +#. A ``routes.py`` module, which contains routing code for the application. + #. A ``views`` package, which contains view code for the application. #. A ``static`` directory, which contains static files, including images and CSS. @@ -853,7 +856,7 @@ also informs Python that the directory which contains it is a *package*. Within this function, application configuration is performed. - Line 7 creates an instance of a :term:`Configurator`. + Line 7 opens a context manager with an instance of a :term:`Configurator`. Line 8 adds support for Jinja2 templating bindings, allowing us to specify renderers with the ``.jinja2`` extension. diff --git a/docs/narr/scaffolding.rst b/docs/narr/scaffolding.rst index 083d831cc..6f64e391f 100644 --- a/docs/narr/scaffolding.rst +++ b/docs/narr/scaffolding.rst @@ -5,7 +5,7 @@ Creating Pyramid Scaffolds .. deprecated:: 1.8 - Scaffolds and the ``pcreate`` script used to generate :app:`Pyramid` projects from scaffolds have been deprecated. Use :ref:`cookiecutters` instead. + Scaffolds and the ``pcreate`` script used to generate :app:`Pyramid` projects from scaffolds have been deprecated. Use :ref:`cookiecutter` instead. You can extend Pyramid by creating a :term:`scaffold` template. A scaffold template is useful if you'd like to distribute a customizable configuration of diff --git a/docs/narr/webob.rst b/docs/narr/webob.rst index e78c524ff..89dc6e0f1 100644 --- a/docs/narr/webob.rst +++ b/docs/narr/webob.rst @@ -345,7 +345,7 @@ against your ``mypackage`` package during application initialization. .. note:: This is only an example. In particular, it is not necessary to cause - ``DBSession.remove`` to be called in an application generated from a + ``DBSession.remove`` to be called in an application generated from the :app:`Pyramid` cookiecutter, because these all use the ``pyramid_tm`` package. The cleanup done by ``DBSession.remove`` is unnecessary when ``pyramid_tm`` :term:`middleware` is configured into the application. -- cgit v1.2.3 From ce2cedb700ec57b75ccad54a0fd5b24a1034c309 Mon Sep 17 00:00:00 2001 From: Stephen Martin Date: Mon, 10 Sep 2018 08:47:02 -0700 Subject: re-pluralize cookiecutter for Sphinx reference --- docs/narr/scaffolding.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr') diff --git a/docs/narr/scaffolding.rst b/docs/narr/scaffolding.rst index 6f64e391f..083d831cc 100644 --- a/docs/narr/scaffolding.rst +++ b/docs/narr/scaffolding.rst @@ -5,7 +5,7 @@ Creating Pyramid Scaffolds .. deprecated:: 1.8 - Scaffolds and the ``pcreate`` script used to generate :app:`Pyramid` projects from scaffolds have been deprecated. Use :ref:`cookiecutter` instead. + Scaffolds and the ``pcreate`` script used to generate :app:`Pyramid` projects from scaffolds have been deprecated. Use :ref:`cookiecutters` instead. You can extend Pyramid by creating a :term:`scaffold` template. A scaffold template is useful if you'd like to distribute a customizable configuration of -- cgit v1.2.3 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 From dfd0697dca6b0431b7d8398d93169c57be5b316b Mon Sep 17 00:00:00 2001 From: Stephen Martin Date: Mon, 17 Sep 2018 13:43:52 -0700 Subject: cookiecutter version history --- docs/narr/cookiecutters.rst | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'docs/narr') diff --git a/docs/narr/cookiecutters.rst b/docs/narr/cookiecutters.rst index f46fc5882..aea118e2c 100644 --- a/docs/narr/cookiecutters.rst +++ b/docs/narr/cookiecutters.rst @@ -3,7 +3,16 @@ Pyramid cookiecutters ===================== +.. versionadded:: 1.8 + Added cookiecutter support. + .. versionadded:: 1.10 + Merged features from ``pyramid-cookiecutter-alchemy`` and ``pyramid-cookiecutter-zodb`` into the single cookiecutter to rule them all, ``pyramid-cookiecutter-starter``. + +.. deprecated:: 1.10 + Merged features from ``pyramid-cookiecutter-alchemy`` and ``pyramid-cookiecutter-zodb`` into the single cookiecutter to rule them all, ``pyramid-cookiecutter-starter``. + ``pyramid-cookiecutter-alchemy`` and ``pyramid-cookiecutter-zodb`` are no longer supported. + Use ``pyramid-cookiecutter-starter`` going forward. 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. -- cgit v1.2.3 From 28e688f1a41215cb6167f8e53de017ddb82b552f Mon Sep 17 00:00:00 2001 From: Stephen Martin Date: Mon, 17 Sep 2018 13:49:04 -0700 Subject: name change --- docs/narr/cookiecutters.rst | 4 ++-- docs/narr/project.rst | 14 +++++++------- 2 files changed, 9 insertions(+), 9 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/cookiecutters.rst b/docs/narr/cookiecutters.rst index aea118e2c..4af7b8df0 100644 --- a/docs/narr/cookiecutters.rst +++ b/docs/narr/cookiecutters.rst @@ -16,11 +16,11 @@ Pyramid cookiecutters 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 unified cookiecutter ``pyramid-cookiecutter-starter`` 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 `_ +* `pyramid-cookiecutter-starter `_ .. seealso:: diff --git a/docs/narr/project.rst b/docs/narr/project.rst index e0d511fba..5560b02c0 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -28,7 +28,7 @@ This cookiecutter is rendered using the ``cookiecutter`` command that you may in .. index:: single: cookiecutters - single: pyramid-cookiecutter-theonecc + single: pyramid-cookiecutter-starter .. _additional_cookiecutters: @@ -43,7 +43,7 @@ The Pyramid cookiecutter released under the Pylons Project offers the following - the mechanism of mapping URLs to code (:term:`URL dispatch` or :term:`traversal`) -* `pyramid-cookiecutter-theonecc `_ +* `pyramid-cookiecutter-starter `_ All configuration options offer a choice of templating language. @@ -83,13 +83,13 @@ On all platforms, generate a project using cookiecutter. .. code-block:: bash - cookiecutter gh:Pylons/pyramid-cookiecutter-theonecc --checkout master + cookiecutter gh:Pylons/pyramid-cookiecutter-starter --checkout master If prompted for the first item, accept the default ``yes`` by hitting return. .. code-block:: text - You've cloned ~/.cookiecutters/pyramid-cookiecutter-theonecc before. + You've cloned ~/.cookiecutters/pyramid-cookiecutter-starter before. Is it okay to delete and re-clone it? [yes]: yes project_name [Pyramid Scaffold]: myproject repo_name [myproject]: myproject @@ -265,7 +265,7 @@ Here's sample output from a test run on Unix: .. 2 passed in 0.47 seconds -The tests themselves are found in the ``tests.py`` module in your ``cookiecutter``-generated project. Within a project generated by the ``pyramid-cookiecutter-theonecc`` cookiecutter, only two sample tests exist. +The tests themselves are found in the ``tests.py`` module in your ``cookiecutter``-generated project. Within a project generated by the ``pyramid-cookiecutter-starter`` cookiecutter, only two sample tests exist. .. note:: @@ -437,7 +437,7 @@ browser like what is displayed in the following image: .. image:: project.png This is the page shown by default when you visit an unmodified ``cookiecutter`` -generated ``pyramid-cookiecutter-theonecc`` application in a browser. +generated ``pyramid-cookiecutter-starter`` application in a browser. .. index:: single: debug toolbar @@ -518,7 +518,7 @@ this: The Project Structure --------------------- -The ``pyramid-cookiecutter-theonecc`` cookiecutter generated a :term:`project` (named ``myproject``), +The ``pyramid-cookiecutter-starter`` cookiecutter generated a :term:`project` (named ``myproject``), which contains a Python :term:`package`. The package is *also* named ``myproject``; the cookiecutter generates a project which contains a package that shares its name. -- cgit v1.2.3 From 66af8f6bc9ead0ad09ca2718131c2dee15352283 Mon Sep 17 00:00:00 2001 From: Stephen Martin Date: Mon, 17 Sep 2018 15:16:52 -0700 Subject: doc fixes --- docs/narr/cookiecutters.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/cookiecutters.rst b/docs/narr/cookiecutters.rst index 4af7b8df0..b4fc2ada7 100644 --- a/docs/narr/cookiecutters.rst +++ b/docs/narr/cookiecutters.rst @@ -3,14 +3,13 @@ Pyramid cookiecutters ===================== -.. versionadded:: 1.8 +.. versionchanged:: 1.8 Added cookiecutter support. .. versionadded:: 1.10 Merged features from ``pyramid-cookiecutter-alchemy`` and ``pyramid-cookiecutter-zodb`` into the single cookiecutter to rule them all, ``pyramid-cookiecutter-starter``. .. deprecated:: 1.10 - Merged features from ``pyramid-cookiecutter-alchemy`` and ``pyramid-cookiecutter-zodb`` into the single cookiecutter to rule them all, ``pyramid-cookiecutter-starter``. ``pyramid-cookiecutter-alchemy`` and ``pyramid-cookiecutter-zodb`` are no longer supported. Use ``pyramid-cookiecutter-starter`` going forward. -- cgit v1.2.3 From 2da2fec698641780a74a039f8abdafeffdb49b0c Mon Sep 17 00:00:00 2001 From: Stephen Martin Date: Mon, 17 Sep 2018 15:39:34 -0700 Subject: fix typo --- docs/narr/cookiecutters.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/cookiecutters.rst b/docs/narr/cookiecutters.rst index b4fc2ada7..9b4b7eeac 100644 --- a/docs/narr/cookiecutters.rst +++ b/docs/narr/cookiecutters.rst @@ -3,10 +3,10 @@ Pyramid cookiecutters ===================== -.. versionchanged:: 1.8 +.. versionadded:: 1.8 Added cookiecutter support. -.. versionadded:: 1.10 +.. versionchanged:: 1.10 Merged features from ``pyramid-cookiecutter-alchemy`` and ``pyramid-cookiecutter-zodb`` into the single cookiecutter to rule them all, ``pyramid-cookiecutter-starter``. .. deprecated:: 1.10 -- cgit v1.2.3 From 2fa1e218ea6b9a6d5c3f8193ea27d0fc44b8964a Mon Sep 17 00:00:00 2001 From: Stephen Martin Date: Mon, 17 Sep 2018 18:20:48 -0700 Subject: version cleanup --- docs/narr/cookiecutters.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/cookiecutters.rst b/docs/narr/cookiecutters.rst index 9b4b7eeac..9883713cb 100644 --- a/docs/narr/cookiecutters.rst +++ b/docs/narr/cookiecutters.rst @@ -2,10 +2,18 @@ Pyramid cookiecutters ===================== +A :term:`cookiecutter` is a command-line utility that creates projects from :ref:`cookiecutters ` (project templates). + +The Pyramid cookiecutter replaced the deprecated Pyramid scaffolds, and should be used going forward. + +`pyramid-cookiecutter-starter `_ .. versionadded:: 1.8 Added cookiecutter support. +.. deprecated:: 1.8 + Scaffolds may be removed in a future version of Pyramid. + .. versionchanged:: 1.10 Merged features from ``pyramid-cookiecutter-alchemy`` and ``pyramid-cookiecutter-zodb`` into the single cookiecutter to rule them all, ``pyramid-cookiecutter-starter``. @@ -13,14 +21,6 @@ Pyramid cookiecutters ``pyramid-cookiecutter-alchemy`` and ``pyramid-cookiecutter-zodb`` are no longer supported. Use ``pyramid-cookiecutter-starter`` going forward. -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-starter`` 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-starter `_ - .. seealso:: See also `Cookiecutter Installation `_ and `Cookiecutter Features `_. Development of cookiecutters is documented under `Learn the Basics of Cookiecutter by Creating a Cookiecutter `_. -- cgit v1.2.3