Permalink
Browse files

updated docs

  • Loading branch information...
1 parent 52403e1 commit 608ff992d3119b434498fe45a1ff305d970b7823 @arthurk arthurk committed Mar 9, 2010
View
@@ -1,144 +1,11 @@
# django-disqus
-Easily integrate [DISQUS](http://disqus.com) comments into your website.
+Export existing comments to and integrate DISQUS_ into your Django_ website.
-* Templatetags
-* Export comments from django.contrib.comments and django-threadedcomments
-* Dump DISQUS JSON data into local file
+Features:
-django-disqus is available open-source under the BSD license.
+- Export django.contrib.comments to DISQUS
+- Dump comments from DISQUS into a local JSON file
+- Templatetags
-The documentation for the upcoming 0.3 release will be available
-at http://arthurk.github.com/django-disqus/
-
-## Installation
-
-1. `pip install django-disqus` or clone the repo and run `python setup.py install`
-2. Add `disqus` to your `INSTALLED_APPS`
-3. Add `DISQUS_API_KEY` and `DISQUS_WEBSITE_SHORTNAME` to your settings. You
-can [get your API key here](http://disqus.com/api/get_my_key/). The shortname
-of your site can be found in the right sidebar ("My Websites") on the
-[DISQUS homepage](http://disqus.com).
-
-Example settings.py:
-
- INSTALLED_APPS = (
- ...
- 'django.contrib.comments',
- 'disqus',
- )
-
- DISQUS_API_KEY = 'FOOBARFOOBARFOOBARFOOBARFOOBARF'
- DISQUS_WEBSITE_SHORTNAME = 'foobar'
-
-## Templatetags
-
-Load the templatetags with `{% load disqus_tags %}`.
-
-### disqus\_dev
-
-Disables url validation and sets the page URL associated with a comment thread
-to the current Site's domain if `DEBUG = True`.
-
-This is neccesary to get comments working on a local development server.
-
- {% load disqus_tags %}
- <head>
- <meta http-equiv="Content-type" content="text/html; charset=utf-8">
- <title>fooar</title>
- {% disqus_dev %}
- </head>
-
-### disqus\_show\_comments
-
-Display comments and comment form.
-
- {% load disqus_tags %}
- {% disqus_show_comments %}
-
-#### Options
-
-* `title`: Defines the comment thread's title.
-* `url`: Defines the page URL associated with a comment thread. Disqus uses this URL to uniquely create and identity a comment thread.
-* `snippet`: Defines the page's content (article or blog post) to use as context.
-* `shortname`: Use a different shortname than `settings.DISQUS_WEBSITE_SHORTNAME`
-
-### disqus\_num\_replies
-
-Replace all URLs that have the `#disqus_thread` anchor with their respective
-comment count.
-
- {% load disqus_tags %}
- <a href="{{ object.get_absolute_url }}#disqus_thread">View Comments</a>
- {% disqus_num_replies %}
-
-### disqus\_recent\_comments
-
-Show recent comments.
-
- {% load disqus_tags %}
- {% disqus_recent_comments %}
-
-#### Options
-
-* `num_items`: Number of comments to show (default: 3)
-* `avatar_size`: Size of the avatars (default: 32)
-* `shortname`: Use a different shortname than `settings.DISQUS_WEBSITE_SHORTNAME`
-
-### disqus\_top\_commenters
-
-Shows top commenters.
-
- {% load disqus_tags %}
- {% disqus_top_commenters %}
-
-##### Options
-
-* `num_items`: Number of comments to show (default: 3)
-* `avatar_size`: Size of the avatars (default: 32)
-* `shortname`: Use a different shortname than `settings.DISQUS_WEBSITE_SHORTNAME`
-* `hide_mod`: Set to 1 to hide moderators
-* `hide_avatars`: Set to 1 to hide avatars
-
-### disqus\_popular\_threads
-
-Shows most popular threads.
-
- {% load disqus_tags %}
- {% disqus_popular_threads %}
-
-#### Options
-
-* `num_items`: Number of comments to show (default: 3)
-* `shortname`: Use a different shortname than `settings.DISQUS_WEBSITE_SHORTNAME`
-
-## Management Commands
-
-### disqus-export
-
-Exports comments from django.contrib.comments to DISQUS.
-
-When exporting comments, make sure you have the domain of your Site set. Also
-the Model to which the comments are associated needs a `get_absolute_url()`
-method which returns the absolute url to the page the comments should
-appear on.
-
-Threaded comments are not supported.
-
-#### Options
-
-* __-d/--dry-run__: Does not export any comments, but merely outputs the
-comments which would have been exported
-* __-v/--verbosity__: Output verbosity level; 0=minimal output, 1=normal output
-
-### disqus-threadedcomments-export
-
-Same as `disqus-export` but exports comments from `disqus-threadedcomments`.
-
-### disqus-dumpdata
-
-The `disqus-dumpdata` command dumps DISQUS comments into a local JSON file.
-
-#### Options
-
-* __--indent__: Specifies the indent level to use when pretty-printing output
+The documentation is available at [http://arthurk.github.com/django-disqus/](http://arthurk.github.com/django-disqus/).
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
View
@@ -3,6 +3,10 @@
Commands
========
+django-disqus provides the following management commands.
+
+.. _disqus_dumpdata:
+
disqus_dumpdata
---------------
@@ -52,16 +56,15 @@ Example output::
}]
-Options
-^^^^^^^
+**Options**:
- ``--indent``: Specifies the indent level to use when pretty-printing output.
Example: ``./manage.py dumpdata --indent=4``
- - ``--filter``: Type of entries (new, spam, killed) that should be returned.
- Types can be combined by separating them with a comma. Example:
+ - ``--filter``: Type of entries (approved, spam, killed) that should be
+ returned. Types can be combined by separating them with a comma. Example:
``./manage.py dumpdata --filter=spam,killed``
- - ``--exclude``: Type of entries (new, spam, killed) that should be excluded.
- Types can be combined by separating them with a comma. Example:
+ - ``--exclude``: Type of entries (approved, spam, killed) that should be
+ excluded. Types can be combined by separating them with a comma. Example:
``./manage.py dumpdata --exclude=spam,killed``
disqus_export
@@ -84,17 +87,13 @@ The command will export all comments that have the ``is_public``
attribute set to ``True`` and ``is_removed`` set to ``False``. To test which
comments will be exported, you can pass the ``--dry-run`` option.
-Options
-^^^^^^^
+**Options**:
- ``-d``/``--dry-run``: Does not export any comments, but merely outputs
the comments which would have been exported. Example:
``./manage.py disqus_export --dry-run``
- - ``--verbosity``: Specify the amount of information that should be printed
- to the console. A verbosity of ``0`` will output nothing. The default
- verbosity is ``1`` and print the title of the comments that are exported.
- Example: ``./manage.py disqus_export --verbosity=0``
-
-disqus_threadedcomments_export
-------------------------------
+ - ``-v``/``--verbosity``: Specify the amount of information that should be
+ printed to the console. A verbosity of ``0`` will output nothing. The
+ default verbosity is ``1`` and print the title of the comments that are
+ exported. Example: ``./manage.py disqus_export --verbosity=0``
View
@@ -47,7 +47,7 @@
# The short X.Y version.
version = '0.3'
# The full version, including alpha/beta/rc tags.
-release = '0.3-dev'
+release = '0.3'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
View
@@ -1,7 +0,0 @@
-.. _disqusapi:
-
-Disqus API
-==========
-
-Using the Disqus API
-
View
@@ -3,12 +3,29 @@
Welcome to django-disqus' documentation!
=========================================
-Contents:
+Export existing comments to and integrate DISQUS_ into your Django_ website.
+
+**Features**:
+
+- Export ``django.contrib.comments`` to DISQUS
+- Dump comments from DISQUS into a local JSON file
+- Templatetags
+
+django-disqus is available open-source under the BSD license. If you'd like
+to help out, you can fork the project at http://github.com/arthurk/django-disqus
+and report any bugs at http://github.com/arthurk/django-disqus/issues.
+
+.. _DISQUS: http://disqus.com
+.. _Django: http://djangoproject.com
+
+Contents
+--------
.. toctree::
:maxdepth: 2
installation
templatetags
commands
- disqusapi
+ releasenotes/index
+
View
@@ -3,28 +3,38 @@
Installation
============
-The easiest way to get django-disqus is if you have setuptools_ installed::
+The easiest way to get django-disqus is if you have pip_ installed::
- easy_install django-disqus
+ pip install django-disqus
-Without setuptools, it's still pretty easy. Download the django-disqus.tgz file from
-`django-disqus's Cheeseshop page`_, untar it and run::
+Without pip, it's still pretty easy. Download the django-disqus.tar.gz file
+from `django-disqus' PyPI page`_, untar it and run::
python setup.py install
-.. _django-disqus's Cheeseshop page: http://pypi.python.org/pypi/django-disqus/
-.. _setuptools: http://peak.telecommunity.com/DevCenter/EasyInstall
+.. _django-disqus' PyPI page: http://pypi.python.org/pypi/django-disqus/
+.. _pip: http://pip.openplans.org/
+Configuring your Django installation
+------------------------------------
-Help and development
---------------------
+First, add ``disqus`` to your ``INSTALLED_APPS``. You **don't** need to run
+``syncdb`` as there are no models provided.
-If you'd like to help out, you can fork the project
-at http://github.com/arthurk/django-disqus and report any bugs
-at http://github.com/arthurk/django-disqus/issues.
+Next, add ``DISQUS_API_KEY`` and ``DISQUS_WEBSITE_SHORTNAME`` to your settings.
+You can `get your API key here`_ (you must be logged in on the DISQUS_
+website). To see the shortname of your website, navigate to Settings->General
+on the DISQUS_ website.
-Configuring your Django installation
-------------------------------------
+Example settings.py::
+
+ INSTALLED_APPS = (
+ ...
+ 'disqus',
+ )
+
+ DISQUS_API_KEY = 'FOOBARFOOBARFOOBARFOOBARFOOBARF'
+ DISQUS_WEBSITE_SHORTNAME = 'foobar'
-Put 'disqus' in INSTALLED_APPS.
-Add SHORTNAME...
+.. _get your API key here: http://disqus.com/api/get_my_key/
+.. _DISQUS: http://disqus.com
View
@@ -0,0 +1,48 @@
+django-disqus 0.3
+=================
+
+**Release Date**: 09-MAR-2010
+
+This release updates django-disqus to use the new DISQUS v1.1 API and
+cleans up the templatetags and management commands.
+
+Management Commands
+-------------------
+
+The following management commands were renamed:
+
+ - ``disqus-dumpdata`` to ``disqus_dumpdata``
+ - ``disqus-export`` to ``disqus_export``
+
+The old names weren't valid Python module identifiers. This lead to
+problems when trying to import them.
+
+The ``disqus_dumpdata`` command has two new options:
+
+ - ``filter``: Type of entries (e.g. spam or killed) that should be returned
+ - ``exclude``: Type of entries that should be excluded from the response
+
+For further information take a look at the documentation for the
+:ref:`disqus_dumpdata` command.
+
+The ``disqus-export-threadedcomments`` command was removed from django-disqus
+because the upcoming ``django-threadedcomments`` release will rely on the
+comment extension hooks provided in Django 1.1. This means that the
+``disqus_export`` command will work just fine when exporting threadedcomments.
+
+Templatetags
+------------
+
+The ``disqus_recent_comments`` templatetag was removed. If you want to use
+this or any other widget, go to the *Tools* section on the DISQUS_ website.
+There you can configure the widget and get the Javascript code that is
+necessary to display it on your website.
+
+The parameters of the ``disqus_show_comments`` tag have changed. Previously
+you could pass the title, url, snippet and shortname. As of this release,
+it's only possible to pass the shortname. If you want to change the
+Javascript variables that the DISQUS comment form uses, take a look at the
+`Configure and override comment system behaviors`_ page in the DISQUS wiki.
+
+.. _`Configure and override comment system behaviors`: http://help.disqus.com/entries/100880-configure-and-override-comment-system-behaviors
+.. _DISQUS: http://disqus.com
@@ -0,0 +1,7 @@
+Release Notes
+=============
+
+.. toctree::
+ :maxdepth: 1
+
+ 0.3
Oops, something went wrong.

0 comments on commit 608ff99

Please sign in to comment.