Ported over docs.

 *.pyc
 *.egg-info
 .tox/
+docs/_build

@@ -16,7 +16,7 @@ import sys, os
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-#sys.path.insert(0, os.path.abspath('.'))
+sys.path.insert(0, os.path.abspath('.'))
 
 # -- General configuration -----------------------------------------------------
 
@@ -25,7 +25,7 @@ import sys, os
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.intersphinx']
+extensions = ['sphinx.ext.intersphinx', 'extensions']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -37,7 +37,7 @@ source_suffix = '.txt'
 #source_encoding = 'utf-8-sig'
 
 # The master toctree document.
-master_doc = 'newindex'
+master_doc = 'index'
 
 # General information about the project.
 project = u'Django Comments'
@@ -286,4 +286,7 @@ epub_copyright = u'2013, Django Software Foundation and contributors'
 
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'http://docs.python.org/': None}
+intersphinx_mapping = {
+    'python': ('http://docs.python.org/', None),
+    'django': ('http://docs.djangoproject.com/en/1.5', 'http://docs.djangoproject.com/en/1.5/_objects'),
+}

@@ -4,8 +4,7 @@
 Example of using the built-in comments app
 ===========================================
 
-Follow the first three steps of the quick start guide in the
-:doc:`documentation </ref/contrib/comments/index>`.
+Follow the first three steps of the :doc:`quick start guide <quickstart>`.
 
 Now suppose, you have an app (``blog``) with a model (``Post``)
 to which you want to attach comments. Let's also suppose that
@@ -82,7 +81,7 @@ It looks for the ``form.html`` under the following directories
 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
+<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
@@ -135,14 +134,14 @@ found under the directory structure we saw for ``form.html``.
 Feeds
 =====
 
-Suppose you want to export a :doc:`feed </ref/contrib/syndication>` of the
+Suppose you want to export a feed__ 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
+  from django_comments.feeds import LatestCommentFeed
 
   urlpatterns = patterns('',
   # ...
@@ -152,6 +151,7 @@ enable it in your project's ``urls.py``:
 
 Now you should have the latest comment feeds being served off ``/feeds/latest/``.
 
+__ https://docs.djangoproject.com/en/1.5/ref/contrib/syndication/
 
 Moderation
 ==========
@@ -159,7 +159,7 @@ 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
+<moderation>`. The comment moderation has the following
 features (all of which or only certain can be enabled):
 
 * Enable comments for a particular model instance.
@@ -174,8 +174,8 @@ following way:
 
 .. code-block:: python
 
-   from django.contrib.comments.moderation import CommentModerator, moderator
    from django.db import models
+   from django_comments.moderation import CommentModerator, moderator
 
    class Post(models.Model):
        title   = models.CharField(max_length = 255)

+def setup(app):
+    app.add_crossref_type(
+        directivename = "setting",
+        rolename      = "setting",
+        indextemplate = "pair: %s; setting",
+    )
+    app.add_crossref_type(
+        directivename = "templatetag",
+        rolename      = "ttag",
+        indextemplate = "pair: %s; template tag"
+    )
+    app.add_crossref_type(
+        directivename = "templatefilter",
+        rolename      = "tfilter",
+        indextemplate = "pair: %s; template filter"
+    )

@@ -2,30 +2,18 @@
 Comment form classes
 ====================
 
-.. module:: django.contrib.comments.forms
+.. module:: django_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>`.
+:doc:`custom comment apps <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.
+   :mod:`django_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.
@@ -33,7 +21,7 @@ you'll use when writing custom views dealing with comments, or when writing
 Abstract comment forms for custom comment apps
 ----------------------------------------------
 
-If you're building a :doc:`custom comment app </ref/contrib/comments/custom>`,
+If you're building a :doc:`custom comment app <custom>`,
 you might want to replace *some* of the form logic but still rely on parts of
 the existing form.
 

@@ -2,21 +2,9 @@
 The built-in comment models
 ===========================
 
-.. module:: django.contrib.comments.models
+.. module:: django_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:
@@ -82,7 +70,7 @@ The built-in comment models
     .. attribute:: is_public
 
         ``False`` if the comment is in moderation (see
-        :doc:`/ref/contrib/comments/moderation`); If ``True``, the comment will
+        :doc:`moderation`); If ``True``, the comment will
         be displayed on the site.
 
     .. attribute:: is_removed

@@ -2,35 +2,22 @@
 Generic comment moderation
 ==========================
 
-.. module:: django.contrib.comments.moderation
+.. module:: django_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
+``django_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``,
+The entire system is contained within ``django_comments.moderation``,
 and uses a two-step process to enable moderation for any given model:
 
 1. A subclass of :class:`CommentModerator`
@@ -66,7 +53,7 @@ new comment is posted on an ``Entry``:
 Accomplishing this is fairly straightforward and requires very little
 code::
 
-    from django.contrib.comments.moderation import CommentModerator, moderator
+    from django_comments.moderation import CommentModerator, moderator
 
     class EntryModerator(CommentModerator):
         email_notification = True
@@ -185,7 +172,7 @@ Registering models for moderation
 ---------------------------------
 
 The moderation system, represented by
-``django.contrib.comments.moderation.moderator`` is an instance of the class
+``django_comments.moderation.moderator`` is an instance of the class
 :class:`Moderator`, which allows registration and "unregistration" of models
 via two methods:
 
@@ -227,8 +214,8 @@ models with an instance of the subclass.
         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
+        attaching listeners to the :data:`~django_comments.signals.comment_will_be_posted`
+        and :data:`~django_comments.signals.comment_was_posted` signals from the
         comment models.
 
     .. method:: pre_save_moderation(sender, comment, request, **kwargs)

@@ -106,8 +106,8 @@ For example::
         ...
     {% endfor %}
 
-This returns a list of :class:`~django.contrib.comments.models.Comment` objects;
-see :doc:`the comment model documentation </ref/contrib/comments/models>` for
+This returns a list of :class:`~django_comments.models.Comment` objects;
+see :doc:`the comment model documentation <models>` for
 details.
 
 .. templatetag:: get_comment_permalink
@@ -195,7 +195,7 @@ 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
+:ttag:`get_comment_form` to get a :class:`form object <django.forms.Form>` that
 you can use in the template::
 
     {% get_comment_form for [object] as [varname] %}
@@ -275,7 +275,7 @@ 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
+Comment Models <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
@@ -317,11 +317,12 @@ should know about:
   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 comments app also depends on the more general `Cross Site Request
+Forgery protection`_ 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.
 
+.. _cross site request forgery protection: https://docs.djangoproject.com/en/1.5/ref/contrib/csrf/
 .. _honeypot: http://en.wikipedia.org/wiki/Honeypot_(computing)

+.. _settings-comments:
+
+=============================================
+Settings that ``django_comments`` understands
+=============================================
+
+.. 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
+<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`.

@@ -2,30 +2,20 @@
 Signals sent by the comments app
 ================================
 
-.. module:: django.contrib.comments.signals
+.. module:: django_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
+The comment app sends a series of signals_ to allow for
+comment moderation and similar activities. See `the introduction to signals`_ for information about how to register for and receive these
 signals.
 
+.. _signals: https://docs.djangoproject.com/en/1.5/topics/signals/
+.. _the introduction to signals: signals_
+
 comment_will_be_posted
 ======================
 
-.. data:: django.contrib.comments.signals.comment_will_be_posted
+.. data:: django_comments.signals.comment_will_be_posted
    :module:
 
 Sent just before a comment will be saved, after it's been sanity checked and
@@ -54,7 +44,7 @@ Arguments sent with this signal:
 comment_was_posted
 ==================
 
-.. data:: django.contrib.comments.signals.comment_was_posted
+.. data:: django_comments.signals.comment_was_posted
    :module:
 
 Sent just after the comment is saved.
@@ -75,7 +65,7 @@ Arguments sent with this signal:
 comment_was_flagged
 ===================
 
-.. data:: django.contrib.comments.signals.comment_was_flagged
+.. data:: django_comments.signals.comment_was_flagged
    :module:
 
 Sent after a comment was "flagged" in some way. Check the flag to see if this
@@ -93,7 +83,7 @@ Arguments sent with this signal:
     :meth:`~django.db.models.Model.save` again.
 
 ``flag``
-    The ``django.contrib.comments.models.CommentFlag`` that's been attached to
+    The ``django_comments.models.CommentFlag`` that's been attached to
     the comment.
 
 ``created``