diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/commands.rst | 45 | ||||
| -rw-r--r-- | docs/configuration.rst | 106 | ||||
| -rw-r--r-- | docs/contributing.rst | 51 | ||||
| -rw-r--r-- | docs/installation.rst | 63 | ||||
| -rw-r--r-- | docs/panels.rst | 192 |
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. |