Updated formtools docs to point at new package outside the Django repo.

Refs #23677.

docs/conf.py

@@ -129,6 +129,7 @@ intersphinx_mapping = {
     'python': ('http://docs.python.org/3/', None),
     'sphinx': ('http://sphinx-doc.org/', None),
     'six': ('http://pythonhosted.org/six/', None),
+    'formtools': ('http://django-formtools.readthedocs.org/en/latest/', None),
 }
 
 # Python's docs don't change every week.

docs/index.txt

@@ -172,10 +172,6 @@ manipulation of form data.
   :doc:`Formsets <topics/forms/formsets>` |
   :doc:`Customizing validation <ref/forms/validation>`
 
-* **Extras:**
-  :doc:`Form preview <ref/contrib/formtools/form-preview>` |
-  :doc:`Form wizard <ref/contrib/formtools/form-wizard>`
-
 The development process
 =======================
 

docs/internals/deprecation.txt

@@ -419,9 +419,8 @@ details on these changes.
   superseded by :setting:`IGNORABLE_404_URLS` in the 1.4 release. They will be
   removed.
 
-* The :doc:`form wizard </ref/contrib/formtools/form-wizard>` has been
-  refactored to use class-based views with pluggable backends in 1.4.
-  The previous implementation will be removed.
+* The form wizard has been refactored to use class-based views with pluggable
+  backends in 1.4. The previous implementation will be removed.
 
 * Legacy ways of calling
   :func:`~django.views.decorators.cache.cache_page` will be removed.

docs/ref/contrib/formtools/form-preview.txt

-============
-Form preview
-============
-
-.. module:: django.contrib.formtools.preview
-    :synopsis: Displays an HTML form, forces a preview, then does something
-               with the submission.
-
-Django comes with an optional "form preview" application that helps automate
-the following workflow:
-
-"Display an HTML form, force a preview, then do something with the submission."
-
-To force a preview of a form submission, all you have to do is write a short
-Python class.
-
-Overview
-=========
-
-Given a :class:`django.forms.Form` subclass that you define, this
-application takes care of the following workflow:
-
-1. Displays the form as HTML on a Web page.
-2. Validates the form data when it's submitted via POST.
-   a. If it's valid, displays a preview page.
-   b. If it's not valid, redisplays the form with error messages.
-3. When the "confirmation" form is submitted from the preview page, calls
-   a hook that you define -- a ``done()`` method that gets passed the valid
-   data.
-
-The framework enforces the required preview by passing a shared-secret hash to
-the preview page via hidden form fields. If somebody tweaks the form parameters
-on the preview page, the form submission will fail the hash-comparison test.
-
-How to use ``FormPreview``
-==========================
-
-1. Point Django at the default FormPreview templates. There are two ways to
-   do this:
-
-   * Add ``'django.contrib.formtools'`` to your
-     :setting:`INSTALLED_APPS` setting. This will work if your
-     :setting:`TEMPLATE_LOADERS` setting includes the
-     ``app_directories`` template loader (which is the case by
-     default). See the :ref:`template loader docs <template-loaders>`
-     for more.
-
-   * Otherwise, determine the full filesystem path to the
-     :file:`django/contrib/formtools/templates` directory, and add that
-     directory to your :setting:`TEMPLATE_DIRS` setting.
-
-2. Create a :class:`~django.contrib.formtools.preview.FormPreview` subclass that
-   overrides the ``done()`` method::
-
-       from django.contrib.formtools.preview import FormPreview
-       from django.http import HttpResponseRedirect
-       from myapp.models import SomeModel
-
-       class SomeModelFormPreview(FormPreview):
-
-           def done(self, request, cleaned_data):
-               # Do something with the cleaned_data, then redirect
-               # to a "success" page.
-               return HttpResponseRedirect('/form/success')
-
-   This method takes an :class:`~django.http.HttpRequest` object and a
-   dictionary of the form data after it has been validated and cleaned.
-   It should return an :class:`~django.http.HttpResponseRedirect` that
-   is the end result of the form being submitted.
-
-3. Change your URLconf to point to an instance of your
-   :class:`~django.contrib.formtools.preview.FormPreview` subclass::
-
-       from myapp.preview import SomeModelFormPreview
-       from myapp.forms import SomeModelForm
-       from django import forms
-
-   ...and add the following line to the appropriate model in your URLconf::
-
-       url(r'^post/$', SomeModelFormPreview(SomeModelForm)),
-
-   where ``SomeModelForm`` is a Form or ModelForm class for the model.
-
-4. Run the Django server and visit :file:`/post/` in your browser.
-
-``FormPreview`` classes
-=======================
-
-.. class:: FormPreview
-
-A :class:`~django.contrib.formtools.preview.FormPreview` class is a simple Python class
-that represents the preview workflow.
-:class:`~django.contrib.formtools.preview.FormPreview` classes must subclass
-``django.contrib.formtools.preview.FormPreview`` and override the ``done()``
-method. They can live anywhere in your codebase.
-
-``FormPreview`` templates
-=========================
-
-.. attribute:: FormPreview.form_template
-.. attribute:: FormPreview.preview_template
-
-By default, the form is rendered via the template :file:`formtools/form.html`,
-and the preview page is rendered via the template :file:`formtools/preview.html`.
-These values can be overridden for a particular form preview by setting
-:attr:`~django.contrib.formtools.preview.FormPreview.preview_template` and
-:attr:`~django.contrib.formtools.preview.FormPreview.form_template` attributes on the
-FormPreview subclass. See :file:`django/contrib/formtools/templates` for the
-default templates.
-
-Advanced ``FormPreview`` methods
-================================
-
-.. method:: FormPreview.process_preview()
-
-    Given a validated form, performs any extra processing before displaying the
-    preview page, and saves any extra data in context.
-
-    By default, this method is empty.  It is called after the form is validated,
-    but before the context is modified with hash information and rendered.

docs/ref/contrib/formtools/index.txt

 django.contrib.formtools
 ========================
 
-.. module:: django.contrib.formtools
-
 A set of high-level abstractions for Django forms (:mod:`django.forms`).
 
-.. toctree::
-   :maxdepth: 1
+Historically, Django shipped with ``django.contrib.formtools`` -- a collection
+of assorted utilities that are useful for specific form use cases. This code is
+now distributed separately from Django, for easier maintenance and to trim the
+size of Django's codebase. In Django 1.8, importing from
+``django.contrib.formtools`` will no longer work.
+
+The new formtools package is named ``django-formtools``, with a main module
+called ``formtools``. Version 1.0 includes the same two primary features that
+the code included when it shipped with Django: a helper for form previews and a
+form wizard view.
+
+See the `official documentation`_ for more information.
+
+.. _official documentation: http://django-formtools.readthedocs.org/
+
+.. _formtools-how-to-migrate:
+
+How to migrate
+--------------
+
+If you've used the old ``django.contrib.formtools`` package follow these
+two easy steps to update your code:
+
+1. Install version 1.0 of the third-party ``django-formtools`` package.
+
+2. Change your app's import statements to reference the new packages.
+
+   For example, change::
+
+       from django.contrib.formtools.wizard.views import WizardView
+
+   to::
+
+       from formtools.wizard.views import WizardView
 
-   form-preview
-   form-wizard
+The code in version 1.0 of the new package is the same (it was copied directly
+from Django), so you don't have to worry about backwards compatibility in terms
+of functionality. Only the imports have changed.

docs/ref/contrib/index.txt

@@ -71,27 +71,6 @@ See the :doc:`flatpages documentation </ref/contrib/flatpages>`.
 
 Requires the sites_ contrib package to be installed as well.
 
-formtools
-=========
-
-A set of high-level abstractions for Django forms (django.forms).
-
-django.contrib.formtools.preview
---------------------------------
-
-An abstraction of the following workflow:
-
-"Display an HTML form, force a preview, then do something with the submission."
-
-See the :doc:`form preview documentation </ref/contrib/formtools/form-preview>`.
-
-django.contrib.formtools.wizard
--------------------------------
-
-Splits forms across multiple Web pages.
-
-See the :doc:`form wizard documentation </ref/contrib/formtools/form-wizard>`.
-
 gis
 ====
 

docs/ref/settings.txt

@@ -2018,11 +2018,11 @@ The secret key is used for:
 * All :doc:`messages </ref/contrib/messages>` if you are using
   :class:`~django.contrib.messages.storage.cookie.CookieStorage` or
   :class:`~django.contrib.messages.storage.fallback.FallbackStorage`.
-* :doc:`Form wizard </ref/contrib/formtools/form-wizard>` progress when using
+* :mod:`Form wizard <formtools.wizard.views>` progress when using
   cookie storage with
-  :class:`django.contrib.formtools.wizard.views.CookieWizardView`.
+  :class:`formtools.wizard.views.CookieWizardView`.
 * All :func:`~django.contrib.auth.views.password_reset` tokens.
-* All in progress :doc:`form previews </ref/contrib/formtools/form-preview>`.
+* All in progress :mod:`form previews <formtools.preview>`.
 * Any usage of :doc:`cryptographic signing </topics/signing>`, unless a
   different key is provided.
 

docs/releases/1.4.txt

@@ -358,7 +358,7 @@ more information.
 New form wizard
 ~~~~~~~~~~~~~~~
 
-The previous ``FormWizard`` from :mod:`django.contrib.formtools` has been
+The previous ``FormWizard`` from ``django.contrib.formtools`` has been
 replaced with a new implementation based on the class-based views
 introduced in Django 1.3. It features a pluggable storage API and doesn't
 require the wizard to pass around hidden fields for every previous step.
@@ -368,9 +368,6 @@ storage backend. The latter uses the tools for
 :doc:`cryptographic signing </topics/signing>` also introduced in
 Django 1.4 to store the wizard's state in the user's cookies.
 
-See the :doc:`form wizard </ref/contrib/formtools/form-wizard>` docs for
-more information.
-
 ``reverse_lazy``
 ~~~~~~~~~~~~~~~~
 

docs/releases/1.7.txt

@@ -440,11 +440,11 @@ Minor features
   enabled. See :ref:`session-invalidation-on-password-change` for more details
   including upgrade considerations when enabling this new middleware.
 
-:mod:`django.contrib.formtools`
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+``django.contrib.formtools``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 * Calls to :meth:`WizardView.done()
-  <django.contrib.formtools.wizard.views.WizardView.done>` now include a
+  <formtools.wizard.views.WizardView.done>` now include a
   ``form_dict`` to allow easier access to forms by their step name.
 
 :mod:`django.contrib.gis`

docs/releases/1.8.txt

@@ -122,17 +122,6 @@ Minor features
   :attr:`~django.contrib.auth.models.CustomUser.REQUIRED_FIELDS` now supports
   :class:`~django.db.models.ForeignKey`\s.
 
-:mod:`django.contrib.formtools`
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-* A :doc:`form wizard </ref/contrib/formtools/form-wizard>` using the
-  :class:`~django.contrib.formtools.wizard.views.CookieWizardView` will now ignore
-  an invalid cookie, and the wizard will restart from the first step. An invalid
-  cookie can occur in cases of intentional manipulation, but also after a secret
-  key change. Previously, this would raise ``WizardViewCookieModified``, a
-  ``SuspiciousOperation``, causing an exception for any user with an invalid cookie
-  upon every request to the wizard, until the cookie is removed.
-
 :mod:`django.contrib.gis`
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -710,6 +699,17 @@ The decorators :func:`~django.test.override_settings` and
 class decorators. As a consequence, when overriding ``setUpClass()`` or
 ``tearDownClass()``, the ``super`` implementation should always be called.
 
+Removal of ``django.contrib.formtools``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The formtools contrib app has been moved into a separate package.
+``django.contrib.formtools`` itself has been removed. The docs provide
+:ref:`migration instructions <formtools-how-to-migrate>`.
+
+The new package is available `on Github`_ and on PyPI.
+
+.. _on GitHub: https://github.com/django/django-formtools/
+
 Miscellaneous
 ~~~~~~~~~~~~~