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/project.rst | 73 +++++++++++++++++++++++++++------------------------ 1 file changed, 38 insertions(+), 35 deletions(-) (limited to 'docs/narr/project.rst') 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. -- 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/project.rst | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) (limited to 'docs/narr/project.rst') 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 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/project.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) (limited to 'docs/narr/project.rst') 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