Migrate info from README to docs.

5 files changed, 457 insertions, 0 deletions

diff --git a/docs/commands.rst b/docs/commands.rst
index 675c188..1d81a05 100644
--- a/docs/commands.rst
+++ b/docs/commands.rst
@@ -1,2 +1,47 @@
 Commands
 ========
+
+The Debug Toolbar currently provides one Django management command.
+
+``debugsqlshell``
+-----------------
+
+This command starts an interactive Python shell, like Django's built-in
+``shell`` management command. In addition, each ORM call that results in a
+database query will be beautifully output in the shell.
+
+Here's an example::
+
+    >>> from page.models import Page
+    >>> ### Lookup and use resulting in an extra query...
+    >>> p = Page.objects.get(pk=1)
+    SELECT "page_page"."id",
+           "page_page"."number",
+           "page_page"."template_id",
+           "page_page"."description"
+    FROM "page_page"
+    WHERE "page_page"."id" = 1
+
+    >>> print p.template.name
+    SELECT "page_template"."id",
+           "page_template"."name",
+           "page_template"."description"
+    FROM "page_template"
+    WHERE "page_template"."id" = 1
+
+    Home
+    >>> ### Using select_related to avoid 2nd database call...
+    >>> p = Page.objects.select_related('template').get(pk=1)
+    SELECT "page_page"."id",
+           "page_page"."number",
+           "page_page"."template_id",
+           "page_page"."description",
+           "page_template"."id",
+           "page_template"."name",
+           "page_template"."description"
+    FROM "page_page"
+    INNER JOIN "page_template" ON ("page_page"."template_id" = "page_template"."id")
+    WHERE "page_page"."id" = 1
+
+    >>> print p.template.name
+    Home
diff --git a/docs/configuration.rst b/docs/configuration.rst
index 6e79ebd..3a8c544 100644
--- a/docs/configuration.rst
+++ b/docs/configuration.rst
@@ -1,2 +1,108 @@
 Configuration
 =============
+
+The debug toolbar has two settings that can be set in ``settings.py``.
+
+#. Optional: Add a tuple called ``DEBUG_TOOLBAR_PANELS`` to your ``settings.py``
+   file that specifies the full Python path to the panel that you want included
+   in the Toolbar. This setting looks very much like the ``MIDDLEWARE_CLASSES``
+   setting. For example::
+
+       DEBUG_TOOLBAR_PANELS = (
+           'debug_toolbar.panels.version.VersionDebugPanel',
+           'debug_toolbar.panels.timer.TimerDebugPanel',
+           'debug_toolbar.panels.settings_vars.SettingsVarsDebugPanel',
+           'debug_toolbar.panels.headers.HeaderDebugPanel',
+           'debug_toolbar.panels.request_vars.RequestVarsDebugPanel',
+           'debug_toolbar.panels.template.TemplateDebugPanel',
+           'debug_toolbar.panels.sql.SQLDebugPanel',
+           'debug_toolbar.panels.signals.SignalDebugPanel',
+           'debug_toolbar.panels.logger.LoggingPanel',
+       )
+
+   You can change the ordering of this tuple to customize the order of the
+   panels you want to display, or add/remove panels. If you have custom panels
+   you can include them in this way -- just provide the full Python path to
+   your panel.
+
+#. Optional: There are a few configuration options to the debug toolbar that
+   can be placed in a dictionary called ``DEBUG_TOOLBAR_CONFIG``:
+
+   * ``INTERCEPT_REDIRECTS``
+
+     If set to True, the debug toolbar will show an intermediate page upon
+     redirect so you can view any debug information prior to redirecting. This
+     page will provide a link to the redirect destination you can follow when
+     ready. If set to False (default), redirects will proceed as normal.
+
+   * ``SHOW_TOOLBAR_CALLBACK``
+
+     If not set or set to None, the debug_toolbar
+     middleware will use its built-in show_toolbar method for determining whether
+     the toolbar should show or not. The default checks are that DEBUG must be
+     set to True and the IP of the request must be in INTERNAL_IPS. You can
+     provide your own method for displaying the toolbar which contains your
+     custom logic. This method should return True or False.
+
+   * ``EXTRA_SIGNALS``
+
+     An array of custom signals that might be in your project,
+     defined as the python path to the signal.
+
+   * ``HIDE_DJANGO_SQL``
+
+     If set to True (the default) then code in Django itself
+     won't be shown in SQL stacktraces.
+
+   * ``SHOW_TEMPLATE_CONTEXT``
+
+     If set to True (the default) then a template's
+     context will be included with it in the Template debug panel. Turning this
+     off is useful when you have large template contexts, or you have template
+     contexts with lazy datastructures that you don't want to be evaluated.
+
+   * ``TAG``
+
+     If set, this will be the tag to which debug_toolbar will attach the
+     debug toolbar. Defaults to 'body'.
+
+   * ``ENABLE_STACKTRACES``
+
+     If set, this will show stacktraces for SQL queries
+     and cache calls. Enabling stacktraces can increase the CPU time used when
+     executing queries. Defaults to True.
+
+   * ``HIDDEN_STACKTRACE_MODULES``
+
+     Useful for eliminating server-related entries which can result
+     in enormous DOM structures and toolbar rendering delays.
+     Default: ``('socketserver', 'threading', 'wsgiref', 'debug_toolbar')``.
+
+     (The first value is ``socketserver`` on Python 3 and ``SocketServer`` on
+     Python 2.)
+
+   * ``ROOT_TAG_ATTRS``
+
+     This setting is injected in the root template div in order to avoid conflicts
+     with client-side frameworks. For example, when using with Angular.js, set
+     this to 'ng-non-bindable' or 'class="ng-non-bindable"'. Defaults to ''.
+
+   * ``SQL_WARNING_THRESHOLD``
+
+     The SQL panel highlights queries that took more that this amount of time,
+     in milliseconds, to execute. The default is 500.
+
+   Example configuration::
+
+       def custom_show_toolbar(request):
+           return True  # Always show toolbar, for example purposes only.
+
+       DEBUG_TOOLBAR_CONFIG = {
+           'INTERCEPT_REDIRECTS': True,
+           'SHOW_TOOLBAR_CALLBACK': custom_show_toolbar,
+           'EXTRA_SIGNALS': ['myproject.signals.MySignal'],
+           'HIDE_DJANGO_SQL': False,
+           'TAG': 'div',
+           'ENABLE_STACKTRACES' : True,
+           'HIDDEN_STACKTRACE_MODULES': ('gunicorn', 'newrelic'),
+       }
diff --git a/docs/contributing.rst b/docs/contributing.rst
index 5a1988f..061d9a3 100644
--- a/docs/contributing.rst
+++ b/docs/contributing.rst
@@ -1,2 +1,53 @@
 Contributing
 ============
+
+Code
+----
+
+The code is available `on GitHub
+<http://github.com/django-debug-toolbar/django-debug-toolbar>`_.
+
+Once you've obtained a checkout, you should create a virtualenv_ and install
+the libraries required for working on the Debug Toolbar::
+
+    $ pip install -r requirements_dev.txt
+
+.. _virtualenv: http://www.virtualenv.org/
+
+Once you've done this, you can run the test suite on all supported version of
+Django and Python::
+
+    $ tox
+
+Bug reports and feature requests
+--------------------------------
+
+You can report bugs and request features in the `bug tracker
+<http://github.com/django-debug-toolbar/django-debug-toolbar/issues>`_.
+
+Please search the existing database for duplicates before filing an issue.
+
+Patches
+-------
+
+Please submit `pull requests
+<http://github.com/django-debug-toolbar/django-debug-toolbar/pulls>`_!
+
+The Debug Toolbar includes a limited but growing test suite. If you fix a bug
+or add a feature code, please consider adding proper coverage in the test
+suite, especially if it has a chance for a regression.
+
+Translations
+------------
+
+Translation efforts are coordinated on `Transifex
+<https://www.transifex.net/projects/p/django-debug-toolbar/>`_.
+
+Help translate the Debug Toolbar in your language!
+
+
+Mailing list
+------------
+
+This project doesn't have a mailing list at this time. If you wish to discuss
+a topic, please open an issue on GitHub.
diff --git a/docs/installation.rst b/docs/installation.rst
index 11e4437..1e228cb 100644
--- a/docs/installation.rst
+++ b/docs/installation.rst
@@ -1,2 +1,65 @@
 Installation
 ============
+
+#. The recommended way to install the Debug Toolbar is via pip_::
+
+       $ pip install django-debug-toolbar
+
+   If you aren't familiar with pip, you may also obtain a copy of the
+   ``debug_toolbar`` directory and add it to your Python path.
+
+   .. _pip: http://www.pip-installer.org/
+
+
+   To test an upcoming release, you can install the `in-development version
+   <http://github.com/django-debug-toolbar/django-debug-toolbar/tarball/master#egg=django-debug-toolbar-dev>`_
+   instead with the following command::
+
+        $ pip install django-debug-toolbar==dev
+
+#. Add the following middleware to your project's ``settings.py`` file::
+
+       MIDDLEWARE_CLASSES = (
+           # ...
+           'debug_toolbar.middleware.DebugToolbarMiddleware',
+           # ...
+       )
+
+   Tying into middleware allows each panel to be instantiated on request and
+   rendering to happen on response.
+
+   The order of ``MIDDLEWARE_CLASSES`` is important: the Debug Toolbar
+   middleware must come after any other middleware that encodes the
+   response's content (such as GZipMiddleware).
+
+   .. note::
+
+      The debug toolbar will only display itself if the mimetype of the
+      response is either ``text/html`` or ``application/xhtml+xml`` and
+      contains a closing ``</body>`` tag.
+
+   .. note ::
+
+      Be aware of middleware ordering and other middleware that may intercept
+      requests and return responses. Putting the debug toolbar middleware
+      *after* the Flatpage middleware, for example, means the toolbar will not
+      show up on flatpages.
+
+#. Make sure your IP is listed in the ``INTERNAL_IPS`` setting. If you are
+   working locally this will be::
+
+       INTERNAL_IPS = ('127.0.0.1',)
+
+   .. note::
+
+      This is required because of the built-in requirements of the
+      ``show_toolbar`` method. See below for how to define a method to
+      determine your own logic for displaying the toolbar.
+
+#. Add ``debug_toolbar`` to your ``INSTALLED_APPS`` setting so Django can
+   find the template files associated with the Debug Toolbar::
+
+       INSTALLED_APPS = (
+           # ...
+           'debug_toolbar',
+       )
diff --git a/docs/panels.rst b/docs/panels.rst
index 7ea0c1a..a4b809e 100644
--- a/docs/panels.rst
+++ b/docs/panels.rst
@@ -1,2 +1,194 @@
 Panels
 ======
+
+The Django Debug Toolbar ships with a series of built-in panels. In addition,
+several third-party panels are available.
+
+Default built-in panels
+-----------------------
+
+The following panels are enabled by default.
+
+Version
+~~~~~~~
+
+Path: ``debug_toolbar.panels.version.VersionDebugPanel``
+
+Django version.
+
+Timer
+~~~~~
+
+Path: ``debug_toolbar.panels.timer.TimerDebugPanel``
+
+Request timer.
+
+Settings
+~~~~~~~~
+
+Path: ``debug_toolbar.panels.settings_vars.SettingsVarsDebugPanel``
+
+A list of settings in settings.py.
+
+Header
+~~~~~~
+
+Path: ``debug_toolbar.panels.headers.HeaderDebugPanel``
+
+Common HTTP headers.
+
+Request
+~~~~~~~
+
+Path: ``debug_toolbar.panels.request_vars.RequestVarsDebugPanel``
+
+GET/POST/cookie/session variable display.
+
+SQL
+~~~
+
+Path: ``debug_toolbar.panels.sql.SQLDebugPanel``
+
+SQL queries including time to execute and links to EXPLAIN each query.
+
+Template
+~~~~~~~~
+
+Path: ``debug_toolbar.panels.template.TemplateDebugPanel``
+
+Templates and context used, and their template paths.
+
+Cache
+~~~~~
+
+Path: ``debug_toolbar.panels.cache.CacheDebugPanel``
+
+Cache queries.
+
+Signal
+~~~~~~
+
+Path: ``debug_toolbar.panels.signals.SignalDebugPanel``
+
+List of signals, their args and receivers.
+
+Logging
+~~~~~~~
+
+Path: ``debug_toolbar.panels.logger.LoggingPanel``
+
+Logging output via Python's built-in :mod:`logging`, or via the `logbook <http://logbook.pocoo.org>`_ module.
+
+Non-default built-in panels
+---------------------------
+
+The following panels are disabled by default. You must add them to the
+``DEBUG_TOOLBAR_PANELS`` setting to enable them.
+
+Profiling
+~~~~~~~~~
+
+Path: ``debug_toolbar.panels.profiling.ProfilingDebugPanel``
+
+Profiling information for the view function.
+
+Third-party panels
+------------------
+
+.. note:: Third-party panels aren't officially supported!
+
+    The authors of the Django Debug Toolbar maintain a list of third-party
+    panels, but they can't vouch for the quality of each of them. Please
+    report bugs to their authors.
+
+If you'd like to add a panel to this list, please submit a pull request!
+
+Haystack
+~~~~~~~~
+
+URL: https://github.com/streeter/django-haystack-panel
+
+Path: ``haystack_panel.panel.HaystackDebugPanel``
+
+See queries made by your Haystack_ backends.
+
+.. _Haystack: http://haystacksearch.org/
+
+HTML Tidy/Validator
+~~~~~~~~~~~~~~~~~~~
+
+URL: https://github.com/joymax/django-dtpanel-htmltidy
+
+Path: ``debug_toolbar_htmltidy.panels.HTMLTidyDebugPanel``
+
+HTML Tidy or HTML Validator is a custom panel that validates your HTML and
+displays warnings and errors.
+
+Inspector
+~~~~~~~~~
+
+URL: https://github.com/santiagobasulto/debug-inspector-panel
+
+Path: ``inspector_panel.panels.inspector.InspectorPanel``
+
+Retrieves and displays information you specify using the ``debug`` statement.
+Inspector panel also logs to the console by default, but may be instructed not
+to.
+
+Memcache
+~~~~~~~~
+
+URL: https://github.com/ross/memcache-debug-panel
+
+Path: ``memcache_toolbar.panels.memcache.MemcachePanel`` or ``memcache_toolbar.panels.pylibmc.PylibmcPanel``
+
+This panel tracks memcached usage. It currently supports both the pylibmc and
+memcache libraries.
+
+MongoDB
+~~~~~~~
+
+URL: https://github.com/hmarr/django-debug-toolbar-mongo
+
+Path: ``debug_toolbar_mongo.panel.MongoDebugPanel``
+
+Adds MongoDB debugging information.
+
+Neo4j
+~~~~~
+
+URL: https://github.com/robinedwards/django-debug-toolbar-neo4j-panel
+
+Path: ``neo4j_panel.Neo4jPanel``
+
+Trace neo4j rest API calls in your django application, this also works for neo4django and neo4jrestclient, support for py2neo is on its way.
+
+Sites
+~~~~~
+
+URL: https://github.com/elvard/django-sites-toolbar
+
+Path: ``sites_toolbar.panels.SitesDebugPanel``
+
+Browse Sites registered in ``django.contrib.sites`` and switch between them.
+Useful to debug project when you use `django-dynamicsites
+<https://bitbucket.org/uysrc/django-dynamicsites/src>`_ which sets SITE_ID
+dynamically.
+
+Template Timings
+~~~~~~~~~~~~~~~~
+
+URL: https://github.com/orf/django-debug-toolbar-template-timings
+
+Path: ``template_timings_panel.panels.TemplateTimings.TemplateTimings``
+
+Displays template rendering times for your Django application.
+
+User
+~~~~
+
+URL: https://github.com/playfire/django-debug-toolbar-user-panel
+
+Path: ``debug_toolbar_user_panel.panels.UserPanel``
+
+Easily switch between logged in users, see properties of current user.