Removed contrib.comments per deprecation timeline.

22 files changed, 21 insertions, 1404 deletions

diff --git a/docs/ref/contrib/comments/custom.txt b/docs/ref/contrib/comments/custom.txt
deleted file mode 100644
index fd70a6a224..0000000000
--- a/docs/ref/contrib/comments/custom.txt
+++ /dev/null
@@ -1,216 +0,0 @@
-==================================
-Customizing the comments framework
-==================================
-
-.. currentmodule:: django.contrib.comments
-
-.. warning::
-
-    Django's comment framework has been deprecated and is no longer supported.
-    Most users will be better served with a custom solution, or a hosted
-    product like Disqus__.
-
-    The code formerly known as ``django.contrib.comments`` is `still available
-    in an external repository`__.
-
-    __ https://disqus.com/
-    __ https://github.com/django/django-contrib-comments
-
-If the built-in comment framework doesn't quite fit your needs, you can extend
-the comment app's behavior to add custom data and logic. The comments framework
-lets you extend the built-in comment model, the built-in comment form, and the
-various comment views.
-
-The :setting:`COMMENTS_APP` setting is where this customization begins. Set
-:setting:`COMMENTS_APP` to the name of the app you'd like to use to provide
-custom behavior. You'll use the same syntax as you'd use for
-:setting:`INSTALLED_APPS`, and the app given must also be in the
-:setting:`INSTALLED_APPS` list.
-
-For example, if you wanted to use an app named ``my_comment_app``, your
-settings file would contain::
-
-    INSTALLED_APPS = [
-        ...
-        'my_comment_app',
-        ...
-    ]
-
-    COMMENTS_APP = 'my_comment_app'
-
-The app named in :setting:`COMMENTS_APP` provides its custom behavior by
-defining some module-level functions in the app's ``__init__.py``. The
-:ref:`complete list of these functions <custom-comment-app-api>` can be found
-below, but first let's look at a quick example.
-
-An example custom comments app
-==============================
-
-One of the most common types of customization is modifying the set of fields
-provided on the built-in comment model. For example, some sites that allow
-comments want the commentator to provide a title for their comment; the built-in
-comment model has no field for that title.
-
-To make this kind of customization, we'll need to do three things:
-
-#. Create a custom comment :class:`~django.db.models.Model` that adds on the
-   "title" field.
-
-#. Create a custom comment :class:`~django.forms.Form` that also adds this
-   "title" field.
-
-#. Inform Django of these objects by defining a few functions in a
-   custom :setting:`COMMENTS_APP`.
-
-So, carrying on the example above, we're dealing with a typical app structure in
-the ``my_comment_app`` directory::
-
-    my_comment_app/
-        __init__.py
-        models.py
-        forms.py
-
-In the ``models.py`` we'll define a ``CommentWithTitle`` model::
-
-    from django.db import models
-    from django.contrib.comments.models import Comment
-
-    class CommentWithTitle(Comment):
-        title = models.CharField(max_length=300)
-
-Most custom comment models will subclass the
-:class:`~django.contrib.comments.models.Comment` model. However,
-if you want to substantially remove or change the fields available in the
-:class:`~django.contrib.comments.models.Comment` model, but don't want to
-rewrite the templates, you could try subclassing from
-``BaseCommentAbstractModel``.
-
-Next, we'll define a custom comment form in ``forms.py``. This is a little more
-tricky: we have to both create a form and override
-``CommentForm.get_comment_model()`` and
-``CommentForm.get_comment_create_data()`` to return deal with our custom title
-field::
-
-    from django import forms
-    from django.contrib.comments.forms import CommentForm
-    from my_comment_app.models import CommentWithTitle
-
-    class CommentFormWithTitle(CommentForm):
-        title = forms.CharField(max_length=300)
-
-        def get_comment_model(self):
-            # Use our custom comment model instead of the built-in one.
-            return CommentWithTitle
-
-        def get_comment_create_data(self):
-            # Use the data of the superclass, and add in the title field
-            data = super(CommentFormWithTitle, self).get_comment_create_data()
-            data['title'] = self.cleaned_data['title']
-            return data
-
-Django provides a couple of "helper" classes to make writing certain types of
-custom comment forms easier; see :mod:`django.contrib.comments.forms` for
-more.
-
-Finally, we'll define a couple of methods in ``my_comment_app/__init__.py`` to
-point Django at these classes we've created::
-
-    from my_comment_app.models import CommentWithTitle
-    from my_comment_app.forms import CommentFormWithTitle
-
-    def get_model():
-        return CommentWithTitle
-
-    def get_form():
-        return CommentFormWithTitle
-
-
-.. warning::
-
-    Be careful not to create cyclic imports in your custom comments app.
-    If you feel your comment configuration isn't being used as defined --
-    for example, if your comment moderation policy isn't being applied --
-    you may have a cyclic import problem.
-
-    If you are having unexplained problems with comments behavior, check
-    if your custom comments application imports (even indirectly)
-    any module that itself imports Django's comments module.
-
-The above process should take care of most common situations. For more
-advanced usage, there are additional methods you can define. Those are
-explained in the next section.
-
-.. _custom-comment-app-api:
-
-Custom comment app API
-======================
-
-The :mod:`django.contrib.comments` app defines the following methods; any
-custom comment app must define at least one of them. All are optional,
-however.
-
-.. function:: get_model()
-
-    Return the :class:`~django.db.models.Model` class to use for comments. This
-    model should inherit from
-    ``django.contrib.comments.models.BaseCommentAbstractModel``, which
-    defines necessary core fields.
-
-    The default implementation returns
-    :class:`django.contrib.comments.models.Comment`.
-
-.. function:: get_form()
-
-    Return the :class:`~django.forms.Form` class you want to use for
-    creating, validating, and saving your comment model.  Your custom
-    comment form should accept an additional first argument,
-    ``target_object``, which is the object the comment will be
-    attached to.
-
-    The default implementation returns
-    :class:`django.contrib.comments.forms.CommentForm`.
-
-    .. note::
-
-        The default comment form also includes a number of unobtrusive
-        spam-prevention features (see
-        :ref:`notes-on-the-comment-form`).  If replacing it with your
-        own form, you may want to look at the source code for the
-        built-in form and consider incorporating similar features.
-
-.. function:: get_form_target()
-
-    Return the URL for POSTing comments. This will be the ``<form action>``
-    attribute when rendering your comment form.
-
-    The default implementation returns a reverse-resolved URL pointing
-    to the ``post_comment()`` view.
-
-    .. note::
-
-        If you provide a custom comment model and/or form, but you
-        want to use the default ``post_comment()`` view, you will
-        need to be aware that it requires the model and form to have
-        certain additional attributes and methods: see the
-        ``django.contrib.comments.views.post_comment()`` view for details.
-
-.. function:: get_flag_url()
-
-    Return the URL for the "flag this comment" view.
-
-    The default implementation returns a reverse-resolved URL pointing
-    to the ``django.contrib.comments.views.moderation.flag()`` view.
-
-.. function:: get_delete_url()
-
-    Return the URL for the "delete this comment" view.
-
-    The default implementation returns a reverse-resolved URL pointing
-    to the ``django.contrib.comments.views.moderation.delete()`` view.
-
-.. function:: get_approve_url()
-
-    Return the URL for the "approve this comment from moderation" view.
-
-    The default implementation returns a reverse-resolved URL pointing
-    to the ``django.contrib.comments.views.moderation.approve()`` view.
diff --git a/docs/ref/contrib/comments/example.txt b/docs/ref/contrib/comments/example.txt
deleted file mode 100644
index abf79c5f14..0000000000
--- a/docs/ref/contrib/comments/example.txt
+++ /dev/null
@@ -1,217 +0,0 @@
-.. highlightlang:: html+django
-
-===========================================
-Example of using the built-in comments app
-===========================================
-
-.. warning::
-
-    Django's comment framework has been deprecated and is no longer supported.
-    Most users will be better served with a custom solution, or a hosted
-    product like Disqus__.
-
-    The code formerly known as ``django.contrib.comments`` is `still available
-    in an external repository`__.
-
-    __ https://disqus.com/
-    __ https://github.com/django/django-contrib-comments
-
-Follow the first three steps of the quick start guide in the
-:doc:`documentation </ref/contrib/comments/index>`.
-
-Now suppose, you have an app (``blog``) with a model (``Post``)
-to which you want to attach comments. Let's also suppose that
-you have a template called ``blog_detail.html`` where you want
-to display the comments list and comment form.
-
-Template
-========
-
-First, we should load the ``comment`` template tags in the
-``blog_detail.html`` so that we can use its functionality. So
-just like all other custom template tag libraries::
-
-    {% load comments %}
-
-Next, let's add the number of comments attached to the particular
-model instance of ``Post``. For this we assume that a context
-variable ``object_pk`` is present which gives the ``id`` of the
-instance of ``Post``.
-
-The usage of the :ttag:`get_comment_count` tag is like below::
-
-   {% get_comment_count for blog.post object_pk as comment_count %}
-   <p>{{ comment_count }} comments have been posted.</p>
-
-If you have the instance (say ``entry``) of the model (``Post``)
-available in the context, then you can refer to it directly::
-
-   {% get_comment_count for entry as comment_count %}
-   <p>{{ comment_count }} comments have been posted.</p>
-
-Next, we can use the :ttag:`render_comment_list` tag, to render all comments
-to the given instance (``entry``) by using the ``comments/list.html`` template::
-
-   {% render_comment_list for entry %}
-
-Django will will look for the ``list.html`` under the following directories
-(for our example)::
-
-  comments/blog/post/list.html
-  comments/blog/list.html
-  comments/list.html
-
-To get a list of comments, we make use of the :ttag:`get_comment_list` tag.
-Using this tag is very similar to the :ttag:`get_comment_count` tag. We
-need to remember that :ttag:`get_comment_list` returns a list of comments
-and hence we have to iterate through them to display them::
-
-   {% get_comment_list for blog.post object_pk as comment_list %}
-   {% for comment in comment_list %}
-   <p>Posted by: {{ comment.user_name }} on {{ comment.submit_date }}</p>
-   ...
-   <p>Comment: {{ comment.comment }}</p>
-   ...
-   {% endfor %}
-
-Finally, we display the comment form, enabling users to enter their
-comments. There are two ways of doing so. The first is when you want to
-display the comments template available under your ``comments/form.html``.
-The other method gives you a chance to customize the form.
-
-The first method makes use of the :ttag:`render_comment_form` tag. Its usage
-too is similar to the other three tags we have discussed above::
-
-   {% render_comment_form for entry %}
-
-It looks for the ``form.html`` under the following directories
-(for our example)::
-
-   comments/blog/post/form.html
-   comments/blog/form.html
-   comments/form.html
-
-Since we customize the form in the second method, we make use of another
-tag called :ttag:`comment_form_target`. This tag on rendering gives the URL
-where the comment form is posted. Without any :doc:`customization
-</ref/contrib/comments/custom>`, :ttag:`comment_form_target` evaluates to
-``/comments/post/``. We use this tag in the form's ``action`` attribute.
-
-The :ttag:`get_comment_form` tag renders a ``form`` for a model instance by
-creating a context variable. One can iterate over the ``form`` object to
-get individual fields. This gives you fine-grain control over the form::
-
-  {% for field in form %}
-  {% ifequal field.name "comment" %}
-    <!-- Customize the "comment" field, say, make CSS changes -->
-  ...
-  {% endfor %}
-
-But let's look at a simple example::
-
-  {% get_comment_form for entry as form %}
-  <!-- A context variable called form is created with the necessary hidden
-  fields, timestamps and security hashes -->
-  <table>
-    <form action="{% comment_form_target %}" method="post">
-      {% csrf_token %}
-      {{ form }}
-      <tr>
-        <td colspan="2">
-          <input type="submit" name="submit" value="Post">
-          <input type="submit" name="preview" value="Preview">
-        </td>
-      </tr>
-    </form>
-  </table>
-
-Flagging
-========
-
-If you want your users to be able to flag comments (say for profanity), you
-can just direct them (by placing a link in your comment list) to ``/flag/{{
-comment.id }}/``. Similarly, a user with requisite permissions (``"Can
-moderate comments"``) can approve and delete comments. This can also be
-done through the ``admin`` as you'll see later. You might also want to
-customize the following templates:
-
-* ``flag.html``
-* ``flagged.html``
-* ``approve.html``
-* ``approved.html``
-* ``delete.html``
-* ``deleted.html``
-
-found under the directory structure we saw for ``form.html``.
-
-Feeds
-=====
-
-Suppose you want to export a :doc:`feed </ref/contrib/syndication>` of the
-latest comments, you can use the built-in ``LatestCommentFeed``. Just
-enable it in your project's ``urls.py``:
-
-.. code-block:: python
-
-  from django.conf.urls import patterns
-  from django.contrib.comments.feeds import LatestCommentFeed
-
-  urlpatterns = patterns('',
-  # ...
-      (r'^feeds/latest/$', LatestCommentFeed()),
-  # ...
-  )
-
-Now you should have the latest comment feeds being served off ``/feeds/latest/``.
-
-
-Moderation
-==========
-
-Now that we have the comments framework working, we might want to have some
-moderation setup to administer the comments. The comments framework comes
-built-in with :doc:`generic comment moderation
-</ref/contrib/comments/moderation>`. The comment moderation has the following
-features (all of which or only certain can be enabled):
-
-* Enable comments for a particular model instance.
-* Close comments after a particular (user-defined) number of days.
-* Email new comments to the site-staff.
-
-To enable comment moderation, we subclass the ``CommentModerator`` and
-register it with the moderation features we want. Let's suppose we want to
-close comments after 7 days of posting and also send out an email to the
-site staff. In ``blog/models.py``, we register a comment moderator in the
-following way:
-
-.. code-block:: python
-
-   from django.contrib.comments.moderation import CommentModerator, moderator
-   from django.db import models
-
-   class Post(models.Model):
-       title   = models.CharField(max_length = 255)
-       content = models.TextField()
-       posted_date = models.DateTimeField()
-
-   class PostModerator(CommentModerator):
-       email_notification = True
-       auto_close_field   = 'posted_date'
-       # Close the comments after 7 days.
-       close_after        = 7
-
-   moderator.register(Post, PostModerator)
-
-The generic comment moderation also has the facility to remove comments.
-These comments can then be moderated by any user who has access to the
-``admin`` site and the ``Can moderate comments`` permission (can be set
-under the ``Users`` page in the ``admin``).
-
-The moderator can ``Flag``, ``Approve`` or ``Remove`` comments using the
-``Action`` drop-down in the ``admin`` under the ``Comments`` page.
-
-.. note::
-
-     Only a super-user will be able to delete comments from the database.
-     ``Remove Comments`` only sets the ``is_public`` attribute to
-     ``False``.
diff --git a/docs/ref/contrib/comments/forms.txt b/docs/ref/contrib/comments/forms.txt
deleted file mode 100644
index f2624ca870..0000000000
--- a/docs/ref/contrib/comments/forms.txt
+++ /dev/null
@@ -1,58 +0,0 @@
-====================
-Comment form classes
-====================
-
-.. module:: django.contrib.comments.forms
-   :synopsis: Forms for dealing with the built-in comment model.
-
-.. warning::
-
-    Django's comment framework has been deprecated and is no longer supported.
-    Most users will be better served with a custom solution, or a hosted
-    product like Disqus__.
-
-    The code formerly known as ``django.contrib.comments`` is `still available
-    in an external repository`__.
-
-    __ https://disqus.com/
-    __ https://github.com/django/django-contrib-comments
-
-The ``django.contrib.comments.forms`` module contains a handful of forms
-you'll use when writing custom views dealing with comments, or when writing
-:doc:`custom comment apps </ref/contrib/comments/custom>`.
-
-.. class:: CommentForm
-
-   The main comment form representing the standard, built-in way of handling
-   submitted comments. This is the class used by all the views
-   :mod:`django.contrib.comments` to handle submitted comments.
-
-   If you want to build custom views that are similar to Django's built-in
-   comment handling views, you'll probably want to use this form.
-
-Abstract comment forms for custom comment apps
-----------------------------------------------
-
-If you're building a :doc:`custom comment app </ref/contrib/comments/custom>`,
-you might want to replace *some* of the form logic but still rely on parts of
-the existing form.
-
-:class:`CommentForm` is actually composed of a couple of abstract base class
-forms that you can subclass to reuse pieces of the form handling logic:
-
-.. class:: CommentSecurityForm
-
-   Handles the anti-spoofing protection aspects of the comment form handling.
-
-   This class contains the ``content_type`` and ``object_pk`` fields pointing
-   to the object the comment is attached to, along with a ``timestamp`` and a
-   ``security_hash`` of all the form data. Together, the timestamp and the
-   security hash ensure that spammers can't "replay" form submissions and
-   flood you with comments.
-
-.. class:: CommentDetailsForm
-
-   Handles the details of the comment itself.
-
-   This class contains the ``name``, ``email``, ``url``, and the ``comment``
-   field itself, along with the associated validation logic.
diff --git a/docs/ref/contrib/comments/index.txt b/docs/ref/contrib/comments/index.txt
deleted file mode 100644
index 35cd137e49..0000000000
--- a/docs/ref/contrib/comments/index.txt
+++ /dev/null
@@ -1,369 +0,0 @@
-===========================
-Django's comments framework
-===========================
-
-.. module:: django.contrib.comments
-   :synopsis: Django's comment framework
-
-.. highlightlang:: html+django
-
-.. warning::
-
-    Django's comment framework has been deprecated and is no longer supported.
-    Most users will be better served with a custom solution, or a hosted
-    product like Disqus__.
-
-    The code formerly known as ``django.contrib.comments`` is `still available
-    in an external repository`__.
-
-    __ https://disqus.com/
-    __ https://github.com/django/django-contrib-comments
-
-Django includes a simple, yet customizable comments framework. The built-in
-comments framework can be used to attach comments to any model, so you can use
-it for comments on blog entries, photos, book chapters, or anything else.
-
-Quick start guide
-=================
-
-To get started using the ``comments`` app, follow these steps:
-
-#. Install the comments framework by adding ``'django.contrib.comments'`` to
-   :setting:`INSTALLED_APPS`.
-
-#. Run ``manage.py migrate`` so that Django will create the comment tables.
-
-#. Add the comment app's URLs to your project's ``urls.py``:
-
-   .. code-block:: python
-
-        urlpatterns = patterns('',
-            ...
-            (r'^comments/', include('django.contrib.comments.urls')),
-            ...
-        )
-
-#. Use the `comment template tags`_ below to embed comments in your
-   templates.
-
-You might also want to examine :ref:`the available settings
-<settings-comments>`.
-
-Comment template tags
-=====================
-
-You'll primarily interact with the comment system through a series of template
-tags that let you embed comments and generate forms for your users to post them.
-
-Like all custom template tag libraries, you'll need to :ref:`load the custom
-tags <loading-custom-template-libraries>` before you can use them::
-
-    {% load comments %}
-
-Once loaded you can use the template tags below.
-
-Specifying which object comments are attached to
-------------------------------------------------
-
-Django's comments are all "attached" to some parent object. This can be any
-instance of a Django model. Each of the tags below gives you a couple of
-different ways you can specify which object to attach to:
-
-#. Refer to the object directly -- the more common method. Most of the
-   time, you'll have some object in the template's context you want
-   to attach the comment to; you can simply use that object.
-
-   For example, in a blog entry page that has a variable named ``entry``,
-   you could use the following to load the number of comments::
-
-        {% get_comment_count for entry as comment_count %}.
-
-#. Refer to the object by content-type and object id. You'd use this method
-   if you, for some reason, don't actually have direct access to the object.
-
-   Following the above example, if you knew the object ID was ``14`` but
-   didn't have access to the actual object, you could do something like::
-
-        {% get_comment_count for blog.entry 14 as comment_count %}
-
-   In the above, ``blog.entry`` is the app label and (lower-cased) model
-   name of the model class.
-
-Displaying comments
--------------------
-
-To display a list of comments, you can use the template tags
-:ttag:`render_comment_list` or :ttag:`get_comment_list`.
-
-.. templatetag:: render_comment_list
-
-Quickly rendering a comment list
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The easiest way to display a list of comments for some object is by using
-:ttag:`render_comment_list`::
-
-    {% render_comment_list for [object] %}
-
-For example::
-
-    {% render_comment_list for event %}
-
-This will render comments using a template named ``comments/list.html``, a
-default version of which is included with Django.
-
-.. templatetag:: get_comment_list
-
-Rendering a custom comment list
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-To get the list of comments for some object, use :ttag:`get_comment_list`::
-
-    {% get_comment_list for [object] as [varname] %}
-
-For example::
-
-    {% get_comment_list for event as comment_list %}
-    {% for comment in comment_list %}
-        ...
-    {% endfor %}
-
-This returns a list of :class:`~django.contrib.comments.models.Comment` objects;
-see :doc:`the comment model documentation </ref/contrib/comments/models>` for
-details.
-
-.. templatetag:: get_comment_permalink
-
-Linking to comments
--------------------
-
-To provide a permalink to a specific comment, use :ttag:`get_comment_permalink`::
-
-    {% get_comment_permalink comment_obj [format_string] %}
-
-By default, the named anchor that will be appended to the URL will be the letter
-'c' followed by the comment id, for example 'c82'. You may specify a custom
-format string if you wish to override this behavior::
-
-    {% get_comment_permalink comment "#c%(id)s-by-%(user_name)s"%}
-
-The format string is a standard python format string. Valid mapping keys
-include any attributes of the comment object.
-
-Regardless of whether you specify a custom anchor pattern, you must supply a
-matching named anchor at a suitable place in your template.
-
-For example::
-
-    {% for comment in comment_list %}
-        <a name="c{{ comment.id }}"></a>
-        <a href="{% get_comment_permalink comment %}">
-            permalink for comment #{{ forloop.counter }}
-        </a>
-        ...
-    {% endfor %}
-
-.. warning::
-
-    There's a `known bug`_ in Safari/WebKit which causes the named anchor to be
-    forgotten following a redirect. The practical impact for comments is that
-    the Safari/webkit browsers will arrive at the correct page but will not
-    scroll to the named anchor.
-
-.. _`known bug`: https://bugs.webkit.org/show_bug.cgi?id=24175
-
-.. templatetag:: get_comment_count
-
-Counting comments
------------------
-
-To count comments attached to an object, use :ttag:`get_comment_count`::
-
-    {% get_comment_count for [object] as [varname]  %}
-
-For example::
-
-        {% get_comment_count for event as comment_count %}
-
-        <p>This event has {{ comment_count }} comments.</p>
-
-
-Displaying the comment post form
---------------------------------
-
-To show the form that users will use to post a comment, you can use
-:ttag:`render_comment_form` or :ttag:`get_comment_form`
-
-.. templatetag:: render_comment_form
-
-Quickly rendering the comment form
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The easiest way to display a comment form is by using
-:ttag:`render_comment_form`::
-
-    {% render_comment_form for [object] %}
-
-For example::
-
-    {% render_comment_form for event %}
-
-This will render comments using a template named ``comments/form.html``, a
-default version of which is included with Django.
-
-.. templatetag:: get_comment_form
-
-Rendering a custom comment form
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If you want more control over the look and feel of the comment form, you may use
-:ttag:`get_comment_form` to get a :doc:`form object </topics/forms/index>` that
-you can use in the template::
-
-    {% get_comment_form for [object] as [varname] %}
-
-A complete form might look like::
-
-    {% get_comment_form for event as form %}
-    <table>
-      <form action="{% comment_form_target %}" method="post">
-        {% csrf_token %}
-        {{ form }}
-        <tr>
-          <td colspan="2">
-            <input type="submit" name="submit" value="Post">
-            <input type="submit" name="preview" value="Preview">
-          </td>
-        </tr>
-      </form>
-    </table>
-
-Be sure to read the `notes on the comment form`_, below, for some special
-considerations you'll need to make if you're using this approach.
-
-.. templatetag:: comment_form_target
-
-Getting the comment form target
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-You may have noticed that the above example uses another template tag --
-:ttag:`comment_form_target` -- to actually get the ``action`` attribute of the
-form. This will always return the correct URL that comments should be posted to;
-you'll always want to use it like above::
-
-    <form action="{% comment_form_target %}" method="post">
-
-Redirecting after the comment post
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-To specify the URL you want to redirect to after the comment has been posted,
-you can include a hidden form input called ``next`` in your comment form. For example::
-
-    <input type="hidden" name="next" value="{% url 'my_comment_was_posted' %}" />
-
-Providing a comment form for authenticated users
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If a user is already authenticated, it makes little sense to display the name,
-email, and URL fields, since these can already be retrieved from their login
-data and profile. In addition, some sites will only accept comments from
-authenticated users.
-
-To provide a comment form for authenticated users, you can manually provide the
-additional fields expected by the Django comments framework. For example,
-assuming comments are attached to the model "object"::
-
-    {% if user.is_authenticated %}
-        {% get_comment_form for object as form %}
-        <form action="{% comment_form_target %}" method="POST">
-        {% csrf_token %}
-        {{ form.comment }}
-        {{ form.honeypot }}
-        {{ form.content_type }}
-        {{ form.object_pk }}
-        {{ form.timestamp }}
-        {{ form.security_hash }}
-        <input type="hidden" name="next" value="{% url 'object_detail_view' object.id %}" />
-        <input type="submit" value="Add comment" id="id_submit" />
-        </form>
-    {% else %}
-        <p>Please <a href="{% url 'auth_login' %}">log in</a> to leave a comment.</p>
-    {% endif %}
-
-The honeypot, content_type, object_pk, timestamp, and security_hash fields are
-fields that would have been created automatically if you had simply used
-``{{ form }}`` in your template, and are referred to in `Notes on the comment
-form`_ below.
-
-Note that we do not need to specify the user to be associated with comments
-submitted by authenticated users. This is possible because the :doc:`Built-in
-Comment Models</ref/contrib/comments/models>` that come with Django associate
-comments with authenticated users by default.
-
-In this example, the honeypot field will still be visible to the user; you'll
-need to hide that field in your CSS::
-
-    #id_honeypot {
-        display: none;
-    }
-
-If you want to accept either anonymous or authenticated comments, replace the
-contents of the "else" clause above with a standard comment form and the right
-thing will happen whether a user is logged in or not.
-
-.. _notes-on-the-comment-form:
-
-Notes on the comment form
--------------------------
-
-The form used by the comment system has a few important anti-spam attributes you
-should know about:
-
-* It contains a number of hidden fields that contain timestamps, information
-  about the object the comment should be attached to, and a "security hash"
-  used to validate this information. If someone tampers with this data --
-  something comment spammers will try -- the comment submission will fail.
-
-  If you're rendering a custom comment form, you'll need to make sure to
-  pass these values through unchanged.
-
-* The timestamp is used to ensure that "reply attacks" can't continue very
-  long. Users who wait too long between requesting the form and posting a
-  comment will have their submissions refused.
-
-* The comment form includes a "honeypot_" field. It's a trap: if any data is
-  entered in that field, the comment will be considered spam (spammers often
-  automatically fill in all fields in an attempt to make valid submissions).
-
-  The default form hides this field with a piece of CSS and further labels
-  it with a warning field; if you use the comment form with a custom
-  template you should be sure to do the same.
-
-The comments app also depends on the more general :doc:`Cross Site Request
-Forgery protection </ref/contrib/csrf>` that comes with Django.  As described in
-the documentation, it is best to use ``CsrfViewMiddleware``.  However, if you
-are not using that, you will need to use the ``csrf_protect`` decorator on any
-views that include the comment form, in order for those views to be able to
-output the CSRF token and cookie.
-
-.. _honeypot: http://en.wikipedia.org/wiki/Honeypot_(computing)
-
-
-Configuration
-=============
-
-See :ref:`comment settings <settings-comments>`.
-
-
-More information
-================
-
-.. toctree::
-   :maxdepth: 1
-
-   models
-   signals
-   custom
-   forms
-   moderation
-   example
diff --git a/docs/ref/contrib/comments/models.txt b/docs/ref/contrib/comments/models.txt
deleted file mode 100644
index 3f9ac740bd..0000000000
--- a/docs/ref/contrib/comments/models.txt
+++ /dev/null
@@ -1,91 +0,0 @@
-===========================
-The built-in comment models
-===========================
-
-.. module:: django.contrib.comments.models
-   :synopsis: The built-in comment models
-
-.. warning::
-
-    Django's comment framework has been deprecated and is no longer supported.
-    Most users will be better served with a custom solution, or a hosted
-    product like Disqus__.
-
-    The code formerly known as ``django.contrib.comments`` is `still available
-    in an external repository`__.
-
-    __ https://disqus.com/
-    __ https://github.com/django/django-contrib-comments
-
-.. class:: Comment
-
-    Django's built-in comment model. Has the following fields:
-
-    .. attribute:: content_object
-
-        A :class:`~django.contrib.contenttypes.fields.GenericForeignKey`
-        attribute pointing to the object the comment is attached to. You can use
-        this to get at the related object (i.e. ``my_comment.content_object``).
-
-        Since this field is a
-        :class:`~django.contrib.contenttypes.fields.GenericForeignKey`, it's
-        actually syntactic sugar on top of two underlying attributes, described
-        below.
-
-    .. attribute:: content_type
-
-        A :class:`~django.db.models.ForeignKey` to
-        :class:`~django.contrib.contenttypes.models.ContentType`; this is the
-        type of the object the comment is attached to.
-
-    .. attribute:: object_pk
-
-        A :class:`~django.db.models.TextField` containing the primary
-        key of the object the comment is attached to.
-
-    .. attribute:: site
-
-        A :class:`~django.db.models.ForeignKey` to the
-        :class:`~django.contrib.sites.models.Site` on which the comment was
-        posted.
-
-    .. attribute:: user
-
-        A :class:`~django.db.models.ForeignKey` to the
-        :class:`~django.contrib.auth.models.User` who posted the comment.
-        May be blank if the comment was posted by an unauthenticated user.
-
-    .. attribute:: user_name
-
-        The name of the user who posted the comment.
-
-    .. attribute:: user_email
-
-        The email of the user who posted the comment.
-
-    .. attribute:: user_url
-
-        The URL entered by the person who posted the comment.
-
-    .. attribute:: comment
-
-        The actual content of the comment itself.
-
-    .. attribute:: submit_date
-
-        The date the comment was submitted.
-
-    .. attribute:: ip_address
-
-        The IP address of the user posting the comment.
-
-    .. attribute:: is_public
-
-        ``False`` if the comment is in moderation (see
-        :doc:`/ref/contrib/comments/moderation`); If ``True``, the comment will
-        be displayed on the site.
-
-    .. attribute:: is_removed
-
-        ``True`` if the comment was removed. Used to keep track of removed
-        comments instead of just deleting them.
diff --git a/docs/ref/contrib/comments/moderation.txt b/docs/ref/contrib/comments/moderation.txt
deleted file mode 100644
index 2f14064191..0000000000
--- a/docs/ref/contrib/comments/moderation.txt
+++ /dev/null
@@ -1,245 +0,0 @@
-==========================
-Generic comment moderation
-==========================
-
-.. module:: django.contrib.comments.moderation
-   :synopsis: Support for automatic comment moderation.
-
-.. warning::
-
-    Django's comment framework has been deprecated and is no longer supported.
-    Most users will be better served with a custom solution, or a hosted
-    product like Disqus__.
-
-    The code formerly known as ``django.contrib.comments`` is `still available
-    in an external repository`__.
-
-    __ https://disqus.com/
-    __ https://github.com/django/django-contrib-comments
-
-Django's bundled comments application is extremely useful on its own,
-but the amount of comment spam circulating on the Web today
-essentially makes it necessary to have some sort of automatic
-moderation system in place for any application which makes use of
-comments. To make this easier to handle in a consistent fashion,
-``django.contrib.comments.moderation`` provides a generic, extensible
-comment-moderation system which can be applied to any model or set of
-models which want to make use of Django's comment system.
-
-
-Overview
-========
-
-The entire system is contained within ``django.contrib.comments.moderation``,
-and uses a two-step process to enable moderation for any given model:
-
-1. A subclass of :class:`CommentModerator`
-   is defined which specifies the moderation options the model wants to
-   enable.
-
-2. The model is registered with the moderation system, passing in the
-   model class and the class which specifies its moderation options.
-
-A simple example is the best illustration of this. Suppose we have the
-following model, which would represent entries in a Weblog::
-
-    from django.db import models
-
-    class Entry(models.Model):
-        title = models.CharField(maxlength=250)
-        body = models.TextField()
-        pub_date = models.DateField()
-        enable_comments = models.BooleanField()
-
-Now, suppose that we want the following steps to be applied whenever a
-new comment is posted on an ``Entry``:
-
-1. If the ``Entry``’s ``enable_comments`` field is ``False``, the
-   comment will simply be disallowed (i.e., immediately deleted).
-
-2. If the ``enable_comments`` field is ``True``, the comment will be
-   allowed to save.
-
-3. Once the comment is saved, an email should be sent to site staff
-   notifying them of the new comment.
-
-Accomplishing this is fairly straightforward and requires very little
-code::
-
-    from django.contrib.comments.moderation import CommentModerator, moderator
-
-    class EntryModerator(CommentModerator):
-        email_notification = True
-        enable_field = 'enable_comments'
-
-    moderator.register(Entry, EntryModerator)
-
-The :class:`CommentModerator` class pre-defines a number of useful moderation
-options which subclasses can enable or disable as desired, and ``moderator``
-knows how to work with them to determine whether to allow a comment, whether
-to moderate a comment which will be allowed to post, and whether to email
-notifications of new comments.
-
-Built-in moderation options
----------------------------
-
-.. class:: CommentModerator
-
-    Most common comment-moderation needs can be handled by subclassing
-    :class:`CommentModerator` and
-    changing the values of pre-defined attributes; the full range of built-in
-    options is as follows.
-
-    .. attribute:: auto_close_field
-
-        If this is set to the name of a
-        :class:`~django.db.models.DateField` or
-        :class:`~django.db.models.DateTimeField` on the model for which
-        comments are being moderated, new comments for objects of that model
-        will be disallowed (immediately deleted) when a certain number of days
-        have passed after the date specified in that field. Must be
-        used in conjunction with :attr:`close_after`, which specifies the
-        number of days past which comments should be
-        disallowed. Default value is ``None``.
-
-    .. attribute:: auto_moderate_field
-
-        Like :attr:`auto_close_field`, but instead of outright deleting
-        new comments when the requisite number of days have elapsed,
-        it will simply set the ``is_public`` field of new comments to
-        ``False`` before saving them. Must be used in conjunction with
-        :attr:`moderate_after`, which specifies the number of days past
-        which comments should be moderated. Default value is ``None``.
-
-    .. attribute:: close_after
-
-        If :attr:`auto_close_field` is used, this must specify the number
-        of days past the value of the field specified by
-        :attr:`auto_close_field` after which new comments for an object
-        should be disallowed. Allowed values are ``None``, 0 (which disallows
-        comments immediately), or any positive integer. Default value is
-        ``None``.
-
-    .. attribute:: email_notification
-
-        If ``True``, any new comment on an object of this model which
-        survives moderation (i.e., is not deleted) will generate an
-        email to site staff. Default value is ``False``.
-
-    .. attribute:: enable_field
-
-        If this is set to the name of a
-        :class:`~django.db.models.BooleanField` on the model
-        for which comments are being moderated, new comments on
-        objects of that model will be disallowed (immediately deleted)
-        whenever the value of that field is ``False`` on the object
-        the comment would be attached to. Default value is ``None``.
-
-    .. attribute:: moderate_after
-
-        If :attr:`auto_moderate_field` is used, this must specify the number
-        of days past the value of the field specified by
-        :attr:`auto_moderate_field` after which new comments for an object
-        should be marked non-public. Allowed values are ``None``, 0 (which
-        moderates comments immediately), or any positive integer. Default
-        value is ``None``.
-
-Simply subclassing :class:`CommentModerator` and changing the values of these
-options will automatically enable the various moderation methods for any
-models registered using the subclass.
-
-Adding custom moderation methods
---------------------------------
-
-For situations where the built-in options listed above are not
-sufficient, subclasses of :class:`CommentModerator` can also override
-the methods which actually perform the moderation, and apply any logic
-they desire.  :class:`CommentModerator` defines three methods which
-determine how moderation will take place; each method will be called
-by the moderation system and passed two arguments: ``comment``, which
-is the new comment being posted, ``content_object``, which is the
-object the comment will be attached to, and ``request``, which is the
-:class:`~django.http.HttpRequest` in which the comment is being submitted:
-
-.. method:: CommentModerator.allow(comment, content_object, request)
-
-    Should return ``True`` if the comment should be allowed to
-    post on the content object, and ``False`` otherwise (in which
-    case the comment will be immediately deleted).
-
-.. method:: CommentModerator.email(comment, content_object, request)
-
-    If email notification of the new comment should be sent to
-    site staff or moderators, this method is responsible for
-    sending the email.
-
-.. method:: CommentModerator.moderate(comment, content_object, request)
-
-    Should return ``True`` if the comment should be moderated (in
-    which case its ``is_public`` field will be set to ``False``
-    before saving), and ``False`` otherwise (in which case the
-    ``is_public`` field will not be changed).
-
-
-Registering models for moderation
----------------------------------
-
-The moderation system, represented by
-``django.contrib.comments.moderation.moderator`` is an instance of the class
-:class:`Moderator`, which allows registration and "unregistration" of models
-via two methods:
-
-.. function:: moderator.register(model_or_iterable, moderation_class)
-
-    Takes two arguments: the first should be either a model class
-    or list of model classes, and the second should be a subclass
-    of ``CommentModerator``, and register the model or models to
-    be moderated using the options defined in the
-    ``CommentModerator`` subclass. If any of the models are
-    already registered for moderation, the exception
-    ``AlreadyModerated`` will be raised.
-
-.. function:: moderator.unregister(model_or_iterable)
-
-    Takes one argument: a model class or list of model classes,
-    and removes the model or models from the set of models which
-    are being moderated. If any of the models are not currently
-    being moderated, the exception ``NotModerated`` will be raised.
-
-
-Customizing the moderation system
----------------------------------
-
-Most use cases will work easily with simple subclassing of
-:class:`CommentModerator` and registration with the provided
-:class:`Moderator` instance, but customization of global moderation behavior
-can be achieved by subclassing :class:`Moderator` and instead registering
-models with an instance of the subclass.
-
-.. class:: Moderator
-
-    In addition to the :func:`moderator.register` and
-    :func:`moderator.unregister` methods detailed above, the following methods
-    on :class:`Moderator` can be overridden to achieve customized behavior:
-
-    .. method:: connect()
-
-        Determines how moderation is set up globally. The base
-        implementation in
-        :class:`Moderator` does this by
-        attaching listeners to the :data:`~django.contrib.comments.signals.comment_will_be_posted`
-        and :data:`~django.contrib.comments.signals.comment_was_posted` signals from the
-        comment models.
-
-    .. method:: pre_save_moderation(sender, comment, request, **kwargs)
-
-        In the base implementation, applies all pre-save moderation
-        steps (such as determining whether the comment needs to be
-        deleted, or whether it needs to be marked as non-public or
-        generate an email).
-
-    .. method:: post_save_moderation(sender, comment, request, **kwargs)
-
-        In the base implementation, applies all post-save moderation
-        steps (currently this consists entirely of deleting comments
-        which were disallowed).
diff --git a/docs/ref/contrib/comments/signals.txt b/docs/ref/contrib/comments/signals.txt
deleted file mode 100644
index f9df8980d7..0000000000
--- a/docs/ref/contrib/comments/signals.txt
+++ /dev/null
@@ -1,103 +0,0 @@
-================================
-Signals sent by the comments app
-================================
-
-.. module:: django.contrib.comments.signals
-   :synopsis: Signals sent by the comment module.
-
-.. warning::
-
-    Django's comment framework has been deprecated and is no longer supported.
-    Most users will be better served with a custom solution, or a hosted
-    product like Disqus__.
-
-    The code formerly known as ``django.contrib.comments`` is `still available
-    in an external repository`__.
-
-    __ https://disqus.com/
-    __ https://github.com/django/django-contrib-comments
-
-The comment app sends a series of :doc:`signals </topics/signals>` to allow for
-comment moderation and similar activities. See :doc:`the introduction to signals
-</topics/signals>` for information about how to register for and receive these
-signals.
-
-comment_will_be_posted
-======================
-
-.. data:: django.contrib.comments.signals.comment_will_be_posted
-   :module:
-
-Sent just before a comment will be saved, after it's been sanity checked and
-submitted. This can be used to modify the comment (in place) with posting
-details or other such actions.
-
-If any receiver returns ``False`` the comment will be discarded and a 400
-response will be returned.
-
-This signal is sent at more or less the same time (just before, actually) as the
-``Comment`` object's :data:`~django.db.models.signals.pre_save` signal.
-
-Arguments sent with this signal:
-
-``sender``
-    The comment model.
-
-``comment``
-    The comment instance about to be posted. Note that it won't have been
-    saved into the database yet, so it won't have a primary key, and any
-    relations might not work correctly yet.
-
-``request``
-    The :class:`~django.http.HttpRequest` that posted the comment.
-
-comment_was_posted
-==================
-
-.. data:: django.contrib.comments.signals.comment_was_posted
-   :module:
-
-Sent just after the comment is saved.
-
-Arguments sent with this signal:
-
-``sender``
-    The comment model.
-
-``comment``
-    The comment instance that was posted. Note that it will have already
-    been saved, so if you modify it you'll need to call
-    :meth:`~django.db.models.Model.save` again.
-
-``request``
-    The :class:`~django.http.HttpRequest` that posted the comment.
-
-comment_was_flagged
-===================
-
-.. data:: django.contrib.comments.signals.comment_was_flagged
-   :module:
-
-Sent after a comment was "flagged" in some way. Check the flag to see if this
-was a user requesting removal of a comment, a moderator approving/removing a
-comment, or some other custom user flag.
-
-Arguments sent with this signal:
-
-``sender``
-    The comment model.
-
-``comment``
-    The comment instance that was posted. Note that it will have already
-    been saved, so if you modify it you'll need to call
-    :meth:`~django.db.models.Model.save` again.
-
-``flag``
-    The ``django.contrib.comments.models.CommentFlag`` that's been attached to
-    the comment.
-
-``created``
-    ``True`` if this is a new flag; ``False`` if it's a duplicate flag.
-
-``request``
-    The :class:`~django.http.HttpRequest` that posted the comment.
diff --git a/docs/ref/contrib/contenttypes.txt b/docs/ref/contrib/contenttypes.txt
index bc8f538857..ee4f7f1318 100644
--- a/docs/ref/contrib/contenttypes.txt
+++ b/docs/ref/contrib/contenttypes.txt
@@ -51,9 +51,6 @@ installed; several of Django's other bundled applications require it:
 * Django's :mod:`authentication framework <django.contrib.auth>` uses it
   to tie user permissions to specific models.
 
-* Django's comments system (:mod:`django.contrib.comments`) uses it to
-  "attach" comments to any installed model.
-
 .. currentmodule:: django.contrib.contenttypes.models
 
 The ``ContentType`` model
@@ -442,8 +439,8 @@ same types of lookups manually::
 Note that if the model in a
 :class:`~django.contrib.contenttypes.fields.GenericRelation` uses a
 non-default value for ``ct_field`` or ``fk_field`` in its
-:class:`~django.contrib.contenttypes.fields.GenericForeignKey` (e.g. the
-:mod:`django.contrib.comments` app uses ``ct_field="object_pk"``),
+:class:`~django.contrib.contenttypes.fields.GenericForeignKey` (for example, if
+you had a ``Comment`` model that uses ``ct_field="object_pk"``),
 you'll need to set ``content_type_field`` and/or ``object_id_field`` in
 the :class:`~django.contrib.contenttypes.fields.GenericRelation` to
 match the ``ct_field`` and ``fk_field``, respectively, in the
diff --git a/docs/ref/contrib/index.txt b/docs/ref/contrib/index.txt
index 3b57ba8c17..533680659e 100644
--- a/docs/ref/contrib/index.txt
+++ b/docs/ref/contrib/index.txt
@@ -24,7 +24,6 @@ those packages have.
 
    admin/index
    auth
-   comments/index
    contenttypes
    csrf
    flatpages
@@ -55,11 +54,6 @@ Django's authentication framework.
 
 See :doc:`/topics/auth/index`.
 
-comments
-========
-
-A simple yet flexible comments system. See :doc:`/ref/contrib/comments/index`.
-
 contenttypes
 ============
 
diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt
index d7b87c0bd7..8f9e7ba053 100644
--- a/docs/ref/settings.txt
+++ b/docs/ref/settings.txt
@@ -1002,14 +1002,12 @@ environment, such as all the currently defined Django settings (from
 ``settings.py``).
 
 As a security measure, Django will *not* include settings that might be
-sensitive (or offensive), such as :setting:`SECRET_KEY` or
-:setting:`PROFANITIES_LIST`. Specifically, it will exclude any setting whose
-name includes any of the following:
+sensitive (or offensive), such as :setting:`SECRET_KEY`. Specifically, it will
+exclude any setting whose name includes any of the following:
 
 * ``'API'``
 * ``'KEY'``
 * ``'PASS'``
-* ``'PROFANITIES_LIST'``
 * ``'SECRET'``
 * ``'SIGNATURE'``
 * ``'TOKEN'``
@@ -2469,53 +2467,6 @@ Default::
      'django.contrib.auth.hashers.UnsaltedMD5PasswordHasher',
      'django.contrib.auth.hashers.CryptPasswordHasher',)
 
-
-.. _settings-comments:
-
-Comments
-========
-
-Settings for :mod:`django.contrib.comments`.
-
-.. setting:: COMMENTS_HIDE_REMOVED
-
-COMMENTS_HIDE_REMOVED
----------------------
-
-If ``True`` (default), removed comments will be excluded from comment
-lists/counts (as taken from template tags). Otherwise, the template author is
-responsible for some sort of a "this comment has been removed by the site staff"
-message.
-
-.. setting:: COMMENT_MAX_LENGTH
-
-COMMENT_MAX_LENGTH
-------------------
-
-The maximum length of the comment field, in characters. Comments longer than
-this will be rejected. Defaults to 3000.
-
-.. setting:: COMMENTS_APP
-
-COMMENTS_APP
-------------
-
-An app which provides :doc:`customization of the comments framework
-</ref/contrib/comments/custom>`.  Use the same dotted-string notation
-as in :setting:`INSTALLED_APPS`.  Your custom :setting:`COMMENTS_APP`
-must also be listed in :setting:`INSTALLED_APPS`.
-
-.. setting:: PROFANITIES_LIST
-
-PROFANITIES_LIST
-----------------
-
-Default: ``()`` (Empty tuple)
-
-A tuple of profanities, as strings, that will be forbidden in comments when
-``COMMENTS_ALLOW_PROFANITIES`` is ``False``.
-
-
 .. _settings-messages:
 
 Messages
diff --git a/docs/ref/signals.txt b/docs/ref/signals.txt
index 25def4490d..7bdb1889ff 100644
--- a/docs/ref/signals.txt
+++ b/docs/ref/signals.txt
@@ -9,9 +9,6 @@ A list of all the signals that Django sends.
     See the documentation on the :doc:`signal dispatcher </topics/signals>` for
     information regarding how to register for and receive signals.
 
-    The :doc:`comment framework </ref/contrib/comments/index>` sends a :doc:`set
-    of comment-related signals </ref/contrib/comments/signals>`.
-
     The :doc:`authentication framework </topics/auth/index>` sends :ref:`signals when
     a user is logged in / out <topics-auth-signals>`.
 
diff --git a/docs/releases/1.0-beta-2.txt b/docs/releases/1.0-beta-2.txt
index 0c5225b6e1..7bd3f396da 100644
--- a/docs/releases/1.0-beta-2.txt
+++ b/docs/releases/1.0-beta-2.txt
@@ -30,11 +30,7 @@ This beta release includes two major features:
 Refactored ``django.contrib.comments``
     As part of a Google Summer of Code project, Thejaswi Puthraya
     carried out a major rewrite and refactoring of Django's bundled
-    comment system, greatly increasing its flexibility and
-    customizability. :doc:`Full documentation
-    </ref/contrib/comments/index>` is available, as well as an
-    upgrade guide if you were using
-    the previous incarnation of the comments application..
+    comment system, greatly increasing its flexibility and customizability.
 
 Refactored documentation
     Django's bundled and online documentation has also been
diff --git a/docs/releases/1.0.txt b/docs/releases/1.0.txt
index 65ecde2fea..1e24ba138f 100644
--- a/docs/releases/1.0.txt
+++ b/docs/releases/1.0.txt
@@ -194,10 +194,7 @@ Refactored ``django.contrib.comments``
 
 As part of a Google Summer of Code project, Thejaswi Puthraya carried out a
 major rewrite and refactoring of Django's bundled comment system, greatly
-increasing its flexibility and customizability. :doc:`Full documentation
-</ref/contrib/comments/index>` is available, as well as an upgrade guide
-if you were using the previous incarnation of
-the comments application.
+increasing its flexibility and customizability.
 
 Removal of deprecated features
 ------------------------------
@@ -244,4 +241,3 @@ backends. However, not all database backends are alike, and in particular many o
 - :ref:`mysql-notes`
 - :ref:`sqlite-notes`
 - :ref:`oracle-notes`
-
diff --git a/docs/releases/1.3-alpha-1.txt b/docs/releases/1.3-alpha-1.txt
index 8898fe67b3..f2c44830e9 100644
--- a/docs/releases/1.3-alpha-1.txt
+++ b/docs/releases/1.3-alpha-1.txt
@@ -234,9 +234,8 @@ No more naughty words
 ~~~~~~~~~~~~~~~~~~~~~
 
 Django has historically provided (and enforced) a list of profanities.
-The :doc:`comments app </ref/contrib/comments/index>` has enforced this
-list of profanities, preventing people from submitting comments that
-contained one of those profanities.
+The comments app has enforced this list of profanities, preventing people from
+submitting comments that contained one of those profanities.
 
 Unfortunately, the technique used to implement this profanities list
 was woefully naive, and prone to the `Scunthorpe problem`_. Fixing the
@@ -246,7 +245,7 @@ framework, we have "fixed" the problem by making the list of
 prohibited words an empty list.
 
 If you want to restore the old behavior, simply put a
-:setting:`PROFANITIES_LIST` setting in your settings file that includes the
+``PROFANITIES_LIST`` setting in your settings file that includes the
 words that you want to prohibit (see the `commit that implemented this
 change`_ if you want to see the list of words that was historically
 prohibited). However, if avoiding profanities is important to you, you
diff --git a/docs/releases/1.3.txt b/docs/releases/1.3.txt
index b77668ac3d..e817e1c3eb 100644
--- a/docs/releases/1.3.txt
+++ b/docs/releases/1.3.txt
@@ -441,9 +441,8 @@ No more naughty words
 ~~~~~~~~~~~~~~~~~~~~~
 
 Django has historically provided (and enforced) a list of profanities.
-The :doc:`comments app </ref/contrib/comments/index>` has enforced this
-list of profanities, preventing people from submitting comments that
-contained one of those profanities.
+The comments app has enforced this list of profanities, preventing people from
+submitting comments that contained one of those profanities.
 
 Unfortunately, the technique used to implement this profanities list
 was woefully naive, and prone to the `Scunthorpe problem`_. Improving
@@ -453,7 +452,7 @@ of a web framework, we have "fixed" the problem by making the list of
 prohibited words an empty list.
 
 If you want to restore the old behavior, simply put a
-:setting:`PROFANITIES_LIST` setting in your settings file that includes the
+``PROFANITIES_LIST`` setting in your settings file that includes the
 words that you want to prohibit (see the `commit that implemented this
 change`_ if you want to see the list of words that was historically
 prohibited). However, if avoiding profanities is important to you, you
diff --git a/docs/releases/1.4-alpha-1.txt b/docs/releases/1.4-alpha-1.txt
index 6dce90bd8c..d27a5b404f 100644
--- a/docs/releases/1.4-alpha-1.txt
+++ b/docs/releases/1.4-alpha-1.txt
@@ -770,7 +770,7 @@ Check their documentation for details.
 `COMMENTS_BANNED_USERS_GROUP` setting
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Django's :doc:`comments app </ref/contrib/comments/index>` has historically
+Django's comments app has historically
 supported excluding the comments of a special user group, but we've never
 documented the feature properly and didn't enforce the exclusion in other parts
 of the app such as the template tags. To fix this problem, we removed the code
@@ -792,8 +792,7 @@ a custom comment model manager to exclude the user group, like this::
             return qs
 
 Save this model manager in your custom comment app (e.g. in
-``my_comments_app/managers.py``) and add it your
-:ref:`custom comment app model <custom-comment-app-api>`::
+``my_comments_app/managers.py``) and add it your custom comment app model::
 
     from django.db import models
     from django.contrib.comments.models import Comment
@@ -805,9 +804,6 @@ Save this model manager in your custom comment app (e.g. in
 
         objects = BanningCommentManager()
 
-For more details, see the documentation about
-:doc:`customizing the comments framework </ref/contrib/comments/custom>`.
-
 `IGNORABLE_404_STARTS` and `IGNORABLE_404_ENDS` settings
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/releases/1.4-beta-1.txt b/docs/releases/1.4-beta-1.txt
index d6074ba0ef..84928ad570 100644
--- a/docs/releases/1.4-beta-1.txt
+++ b/docs/releases/1.4-beta-1.txt
@@ -838,7 +838,7 @@ Check their documentation for details.
 `COMMENTS_BANNED_USERS_GROUP` setting
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Django's :doc:`comments app </ref/contrib/comments/index>` has historically
+Django's comments app has historically
 supported excluding the comments of a special user group, but we've never
 documented the feature properly and didn't enforce the exclusion in other parts
 of the app such as the template tags. To fix this problem, we removed the code
@@ -860,8 +860,7 @@ a custom comment model manager to exclude the user group, like this::
             return qs
 
 Save this model manager in your custom comment app (e.g. in
-``my_comments_app/managers.py``) and add it your
-:ref:`custom comment app model <custom-comment-app-api>`::
+``my_comments_app/managers.py``) and add it your custom comment app model::
 
     from django.db import models
     from django.contrib.comments.models import Comment
@@ -873,9 +872,6 @@ Save this model manager in your custom comment app (e.g. in
 
         objects = BanningCommentManager()
 
-For more details, see the documentation about
-:doc:`customizing the comments framework </ref/contrib/comments/custom>`.
-
 `IGNORABLE_404_STARTS` and `IGNORABLE_404_ENDS` settings
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/releases/1.4.6.txt b/docs/releases/1.4.6.txt
index cac640ad97..e6ed040c42 100644
--- a/docs/releases/1.4.6.txt
+++ b/docs/releases/1.4.6.txt
@@ -13,7 +13,7 @@ Mitigated possible XSS attack via user-supplied redirect URLs
 -------------------------------------------------------------
 
 Django relies on user input in some cases (e.g.
-:func:`django.contrib.auth.views.login`, :mod:`django.contrib.comments`, and
+:func:`django.contrib.auth.views.login`, ``django.contrib.comments``, and
 :doc:`i18n </topics/i18n/index>`) to redirect the user to an "on success" URL.
 The security checks for these redirects (namely
 ``django.util.http.is_safe_url()``) didn't check if the scheme is ``http(s)``
diff --git a/docs/releases/1.4.txt b/docs/releases/1.4.txt
index 054a89a778..436645d87f 100644
--- a/docs/releases/1.4.txt
+++ b/docs/releases/1.4.txt
@@ -923,7 +923,7 @@ Check their documentation for details.
 `COMMENTS_BANNED_USERS_GROUP` setting
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Django's :doc:`comments app </ref/contrib/comments/index>` has historically
+Django's comments has historically
 supported excluding the comments of a special user group, but we've never
 documented the feature properly and didn't enforce the exclusion in other parts
 of the app such as the template tags. To fix this problem, we removed the code
@@ -945,8 +945,7 @@ comment model manager to exclude the user group, like this::
             return qs
 
 Save this model manager in your custom comment app (e.g., in
-``my_comments_app/managers.py``) and add it your
-:ref:`custom comment app model <custom-comment-app-api>`::
+``my_comments_app/managers.py``) and add it your custom comment app model::
 
     from django.db import models
     from django.contrib.comments.models import Comment
@@ -958,9 +957,6 @@ Save this model manager in your custom comment app (e.g., in
 
         objects = BanningCommentManager()
 
-For more details, see the documentation about
-:doc:`customizing the comments framework </ref/contrib/comments/custom>`.
-
 `IGNORABLE_404_STARTS` and `IGNORABLE_404_ENDS` settings
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/releases/1.5.2.txt b/docs/releases/1.5.2.txt
index 6414aab509..01147951b7 100644
--- a/docs/releases/1.5.2.txt
+++ b/docs/releases/1.5.2.txt
@@ -10,7 +10,7 @@ Mitigated possible XSS attack via user-supplied redirect URLs
 -------------------------------------------------------------
 
 Django relies on user input in some cases (e.g.
-:func:`django.contrib.auth.views.login`, :mod:`django.contrib.comments`, and
+:func:`django.contrib.auth.views.login`, ``django.contrib.comments``, and
 :doc:`i18n </topics/i18n/index>`) to redirect the user to an "on success" URL.
 The security checks for these redirects (namely
 ``django.util.http.is_safe_url()``) didn't check if the scheme is ``http(s)``
diff --git a/docs/releases/1.6.txt b/docs/releases/1.6.txt
index d3c9dca22e..5e7134a714 100644
--- a/docs/releases/1.6.txt
+++ b/docs/releases/1.6.txt
@@ -589,7 +589,7 @@ your code.
 Storage of IP addresses in the comments app
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The :doc:`comments </ref/contrib/comments/index>` app now uses a
+The comments app now uses a
 ``GenericIPAddressField`` for storing commenters' IP addresses, to support
 comments submitted from IPv6 addresses. Until now, it stored them in an
 ``IPAddressField``, which is only meant to support IPv4. When saving a comment
diff --git a/docs/topics/http/urls.txt b/docs/topics/http/urls.txt
index 36a43ed704..b8d73d572b 100644
--- a/docs/topics/http/urls.txt
+++ b/docs/topics/http/urls.txt
@@ -336,7 +336,6 @@ itself. It includes a number of other URLconfs::
 
     urlpatterns = patterns('',
         # ... snip ...
-        url(r'^comments/', include('django.contrib.comments.urls')),
         url(r'^community/', include('django_website.aggregator.urls')),
         url(r'^contact/', include('django_website.contact.urls')),
         # ... snip ...