Merge pull request #3406 from mmerickel/drop-pcreate

initial work removing pcreate

10 files changed, 7 insertions, 233 deletions

diff --git a/docs/api/scaffolds.rst b/docs/api/scaffolds.rst
deleted file mode 100644
index 827962e19..000000000
--- a/docs/api/scaffolds.rst
+++ /dev/null
@@ -1,13 +0,0 @@
-.. _scaffolds_module:
-
-:mod:`pyramid.scaffolds`
-------------------------
-
-.. automodule:: pyramid.scaffolds
-
-  .. autoclass:: pyramid.scaffolds.Template
-     :members:
-
-  .. autoclass:: pyramid.scaffolds.PyramidTemplate
-     :members:
-
diff --git a/docs/glossary.rst b/docs/glossary.rst
index e5566a229..4668efe6d 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -1005,15 +1005,6 @@ Glossary
      :term:`cookiecutter`.  For more information, see
      https://docs.pylonsproject.org/projects/pyramid_debugtoolbar/en/latest/.
 
-   scaffold
-     A project template that generates some of the major parts of a Pyramid
-     application and helps users to quickly get started writing larger
-     applications.  Scaffolds are usually used via the ``pcreate`` command.
-
-     .. deprecated:: 1.8
-
-     .. seealso:: See also :term:`cookiecutter`.
-
    pyramid_exclog
      A package which logs Pyramid application exception (error) information
      to a standard Python logger.  This add-on is most useful when
@@ -1162,8 +1153,6 @@ Glossary
           ``pyramid-cookiecutter-alchemy`` and ``pyramid-cookiecutter-zodb`` are no longer supported.
           Use ``pyramid-cookiecutter-starter`` going forward.
 
-      .. seealso:: See also :term:`scaffold`.
-
    coverage
       A measurement of code coverage, usually expressed as a percentage of which lines of code have been executed over which lines are executable, typically run during test execution.
 
diff --git a/docs/index.rst b/docs/index.rst
index 5dba6eec5..a1a81872c 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -140,7 +140,6 @@ Narrative documentation in chapter form explaining how to use :app:`Pyramid`.
    narr/advconfig
    narr/extconfig
    narr/cookiecutters
-   narr/scaffolding
    narr/upgrading
    narr/threadlocals
    narr/zca
diff --git a/docs/latexindex.rst b/docs/latexindex.rst
index 0a6b3400f..2db39bf1a 100644
--- a/docs/latexindex.rst
+++ b/docs/latexindex.rst
@@ -79,7 +79,6 @@ Narrative Documentation
    narr/advconfig
    narr/extconfig
    narr/cookiecutters
-   narr/scaffolding
    narr/upgrading
    narr/threadlocals
    narr/zca
diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst
index 7af6bba43..b571a7d7b 100644
--- a/docs/narr/commandline.rst
+++ b/docs/narr/commandline.rst
@@ -1131,6 +1131,6 @@ start with either ``foo`` or ``bar``:
     reload_assets                                False
     prevent_http_cache                           False
 
-Pyramid's ``pserve``, ``pcreate``, ``pshell``, ``prequest``, ``ptweens``, and
+Pyramid's ``pserve``, ``pshell``, ``prequest``, ``ptweens``, and
 other ``p*`` scripts are implemented as console scripts.  When you invoke one
 of those, you are using a console script.
diff --git a/docs/narr/cookiecutters.rst b/docs/narr/cookiecutters.rst
index 9883713cb..c6829056c 100644
--- a/docs/narr/cookiecutters.rst
+++ b/docs/narr/cookiecutters.rst
@@ -2,18 +2,14 @@
 
 Pyramid cookiecutters
 =====================
-A :term:`cookiecutter` is a command-line utility that creates projects from :ref:`cookiecutters <cookiecutter:readme>` (project templates).
 
-The Pyramid cookiecutter replaced the deprecated Pyramid scaffolds, and should be used going forward.
+A :term:`cookiecutter` is a command-line utility that creates projects from :ref:`cookiecutters <cookiecutter:readme>` (project templates).
 
 `pyramid-cookiecutter-starter <https://github.com/Pylons/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``.
 
@@ -24,7 +20,3 @@ The Pyramid cookiecutter replaced the deprecated Pyramid scaffolds, and should b
 .. seealso::
 
     See also `Cookiecutter Installation <https://cookiecutter.readthedocs.io/en/latest/installation.html>`_ and `Cookiecutter Features <https://cookiecutter.readthedocs.io/en/latest/readme.html#features>`_. Development of cookiecutters is documented under `Learn the Basics of Cookiecutter by Creating a Cookiecutter <https://cookiecutter.readthedocs.io/en/latest/first_steps.html>`_.
-
-.. seealso::
-
-    See also :term:`scaffold`.
diff --git a/docs/narr/scaffolding.rst b/docs/narr/scaffolding.rst
deleted file mode 100644
index 47eb2c658..000000000
--- a/docs/narr/scaffolding.rst
+++ /dev/null
@@ -1,184 +0,0 @@
-.. _scaffolding_chapter:
-
-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.
-
-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
-Pyramid to other users.  Once you've created a scaffold, and someone has
-installed the distribution that houses the scaffold, they can use the
-``pcreate`` script to create a custom version of your scaffold's template.
-Pyramid itself uses scaffolds to allow people to bootstrap new projects.  For
-example, ``pcreate -s alchemy MyStuff`` causes Pyramid to render the
-``alchemy`` scaffold template to the ``MyStuff`` directory.
-
-Basics
-------
-
-A scaffold template is just a bunch of source files and directories on disk. A
-small definition class points at this directory.  It is in turn pointed at by a
-:term:`Setuptools` "entry point" which registers the scaffold so it can be
-found by the ``pcreate`` command.
-
-To create a scaffold template, create a Python :term:`distribution` to house
-the scaffold which includes a ``setup.py`` that relies on the :term:`Setuptools`
-package.  See `Packaging and Distributing Projects
-<https://packaging.python.org/tutorials/packaging-projects/>`_ for more information
-about how to do this.  For example, we'll pretend the distribution you create
-is named ``CoolExtension``, and it has a package directory within it named
-``coolextension``.
-
-Once you've created the distribution, put a "scaffolds" directory within your
-distribution's package directory, and create a file within that directory named
-``__init__.py`` with something like the following:
-
-.. code-block:: python
-    :linenos:
-
-    # CoolExtension/coolextension/scaffolds/__init__.py
-
-    from pyramid.scaffolds import PyramidTemplate
-
-    class CoolExtensionTemplate(PyramidTemplate):
-        _template_dir = 'coolextension_scaffold'
-        summary = 'My cool extension'
-
-Once this is done, within the ``scaffolds`` directory, create a template
-directory.  Our example used a template directory named
-``coolextension_scaffold``.
-
-As you create files and directories within the template directory, note that:
-
-- Files which have a name which are suffixed with the value ``_tmpl`` will be
-  rendered, and replacing any instance of the literal string ``{{var}}`` with
-  the string value of the variable named ``var`` provided to the scaffold.
-
-- Files and directories with filenames that contain the string ``+var+`` will
-  have that string replaced with the value of the ``var`` variable provided to
-  the scaffold.
-
-- Files that start with a dot (e.g., ``.env``) are ignored and will not be
-  copied over to the destination directory. If you want to include a file with
-  a leading dot, then you must replace the dot with ``+dot+`` (e.g.,
-  ``+dot+env``).
-
-Otherwise, files and directories which live in the template directory will be
-copied directly without modification to the ``pcreate`` output location.
-
-The variables provided by the default ``PyramidTemplate`` include ``project``
-(the project name provided by the user as an argument to ``pcreate``),
-``package`` (a lowercasing and normalizing of the project name provided by the
-user), ``random_string`` (a long random string), and ``package_logger`` (the
-name of the package's logger).
-
-See Pyramid's "scaffolds" package
-(https://github.com/Pylons/pyramid/tree/master/pyramid/scaffolds) for concrete
-examples of scaffold directories (``zodb``, ``alchemy``, and ``starter``, for
-example).
-
-After you've created the template directory, add the following to the
-``entry_points`` value of your distribution's ``setup.py``:
-
-.. code-block:: ini
-
-    [pyramid.scaffold]
-    coolextension=coolextension.scaffolds:CoolExtensionTemplate
-
-For example:
-
-.. code-block:: python
-
-    def setup(
-        #...,
-        entry_points = """\
-            [pyramid.scaffold]
-            coolextension=coolextension.scaffolds:CoolExtensionTemplate
-        """
-        )
-
-Run your distribution's ``setup.py develop`` or ``setup.py install`` command.
-After that, you should be able to see your scaffolding template listed when you
-run ``pcreate -l``.  It will be named ``coolextension`` because that's the name
-we gave it in the entry point setup.  Running ``pcreate -s coolextension
-MyStuff`` will then render your scaffold to an output directory named
-``MyStuff``.
-
-See the module documentation for :mod:`pyramid.scaffolds` for information about
-the API of the :class:`pyramid.scaffolds.Template` class and related classes.
-You can override methods of this class to get special behavior.
-
-Supporting Older Pyramid Versions
----------------------------------
-
-Because different versions of Pyramid handled scaffolding differently, if you
-want to have extension scaffolds that can work across Pyramid 1.0.X, 1.1.X,
-1.2.X and 1.3.X, you'll need to use something like this bit of horror while
-defining your scaffold template:
-
-.. code-block:: python
-    :linenos:
-
-    try: # pyramid 1.0.X
-        # "pyramid.paster.paste_script..." doesn't exist past 1.0.X
-        from pyramid.paster import paste_script_template_renderer
-        from pyramid.paster import PyramidTemplate
-    except ImportError:
-        try: # pyramid 1.1.X, 1.2.X
-            # trying to import "paste_script_template_renderer" fails on 1.3.X
-            from pyramid.scaffolds import paste_script_template_renderer
-            from pyramid.scaffolds import PyramidTemplate
-        except ImportError: # pyramid >=1.3a2
-            paste_script_template_renderer = None
-            from pyramid.scaffolds import PyramidTemplate
-
-    class CoolExtensionTemplate(PyramidTemplate):
-        _template_dir = 'coolextension_scaffold'
-        summary = 'My cool extension'
-        template_renderer = staticmethod(paste_script_template_renderer)
-
-And then in the setup.py of the package that contains your scaffold, define
-the template as a target of both ``paste.paster_create_template`` (for
-``paster create``) and ``pyramid.scaffold`` (for ``pcreate``).
-
-.. code-block:: ini
-
-    [paste.paster_create_template]
-    coolextension=coolextension.scaffolds:CoolExtensionTemplate
-    [pyramid.scaffold]
-    coolextension=coolextension.scaffolds:CoolExtensionTemplate
-
-Doing this hideousness will allow your scaffold to work as a ``paster create``
-target (under 1.0, 1.1, or 1.2) or as a ``pcreate`` target (under 1.3).  If an
-invoker tries to run ``paster create`` against a scaffold defined this way
-under 1.3, an error is raised instructing them to use ``pcreate`` instead.
-
-If you want to support Pyramid 1.3 only, it's much cleaner, and the API is
-stable:
-
-.. code-block:: python
-    :linenos:
-
-    from pyramid.scaffolds import PyramidTemplate
-
-    class CoolExtensionTemplate(PyramidTemplate):
-        _template_dir = 'coolextension_scaffold'
-        summary = 'My cool_extension'
-
-You only need to specify a ``paste.paster_create_template`` entry point target
-in your ``setup.py`` if you want your scaffold to be consumable by users of
-Pyramid 1.0, 1.1, or 1.2.  To support only 1.3, specifying only the
-``pyramid.scaffold`` entry point is good enough.  If you want to support both
-``paster create`` and ``pcreate`` (meaning you want to support Pyramid 1.2 and
-some older version), you'll need to define both.
-
-Examples
---------
-
-Existing third-party distributions which house scaffolding are available via
-:term:`PyPI`.  The ``pyramid_jqm``, ``pyramid_zcml``, and ``pyramid_jinja2``
-packages house scaffolds.  You can install and examine these packages to see
-how they work in the quest to develop your own scaffolding.
diff --git a/docs/pscripts/pcreate.rst b/docs/pscripts/pcreate.rst
deleted file mode 100644
index e2c45626a..000000000
--- a/docs/pscripts/pcreate.rst
+++ /dev/null
@@ -1,9 +0,0 @@
-.. index::
-    single: pcreate; --help
-
-.. _pcreate_script:
-
-.. autoprogram:: pyramid.scripts.pcreate:PCreateCommand.parser
-    :prog: pcreate
-
-.. seealso:: :ref:`creating_a_project` and :ref:`running-pscripts`.
diff --git a/docs/tutorials/wiki/NOTE-relocatable.txt b/docs/tutorials/wiki/NOTE-relocatable.txt
index e942caba8..c3f30af51 100644
--- a/docs/tutorials/wiki/NOTE-relocatable.txt
+++ b/docs/tutorials/wiki/NOTE-relocatable.txt
@@ -1,6 +1,7 @@
 We specifically use relative package references where possible so this demo
-works even if the user names their package (in the '$VENV/bin/pcreate -s
-zodb ...' step) something other than 'tutorial'.
+works even if the user names their package (in the
+'cookiecutter gh:Pylons/pyramid-cookiecutter-starter' step) something other
+than 'tutorial'.
 
 Specifically:
 
@@ -9,5 +10,5 @@ Specifically:
   page templates.
 
 Direct uses of the package name, like in __init__.py 'config.scan()'
-statements, are already adjusted by the paster/pcreate, so we don't have to
+statements, are already adjusted by the cookiecutter, so we don't have to
 worry about them.
diff --git a/docs/whatsnew-1.3.rst b/docs/whatsnew-1.3.rst
index 8de69c450..a09dc68a2 100644
--- a/docs/whatsnew-1.3.rst
+++ b/docs/whatsnew-1.3.rst
@@ -514,7 +514,7 @@ Documentation Enhancements
 
 - Added an API docs chapter for :mod:`pyramid.scaffolds`.
 
-- Added a narrative docs chapter named :ref:`scaffolding_chapter`.
+- Added a narrative docs chapter named "Creating Pyramid Scaffolds".
 
 - Added a description of the ``prequest`` command-line script at
   :ref:`invoking_a_request`.