Skip to content

Commit 73af56d

Browse files
jezdezjezdez
committed
Cosmetic fixes to the README file.
1 parent 4c3474b commit 73af56d

File tree

1 file changed

+87
-73
lines changed

1 file changed

+87
-73
lines changed

‎README.rst

Lines changed: 87 additions & 73 deletions
Original file line numberDiff line numberDiff line change
@@ -20,8 +20,8 @@ Currently, the following panels have been written and are working:
2020

2121
There is also one Django management command currently:
2222

23-
- `debugsqlshell`: Outputs the SQL that gets executed as you work in the Python
24-
interactive shell. (See example below)
23+
- ``debugsqlshell``: Outputs the SQL that gets executed as you work in the
24+
Python interactive shell. (See example below)
2525

2626
If you have ideas for other panels please let us know.
2727

@@ -30,129 +30,143 @@ If you have ideas for other panels please let us know.
3030
Installation
3131
============
3232

33-
#. Add the `debug_toolbar` directory to your Python path.
33+
#. Add the ``debug_toolbar`` directory to your Python path.
3434

35-
#. Add the following middleware to your project's `settings.py` file::
35+
#. Add the following middleware to your project's ``settings.py`` file::
3636

37-
'debug_toolbar.middleware.DebugToolbarMiddleware',
37+
MIDDLEWARE_CLASSES = (
38+
# ...
39+
'debug_toolbar.middleware.DebugToolbarMiddleware',
40+
# ...
41+
)
3842

3943
Tying into middleware allows each panel to be instantiated on request and
4044
rendering to happen on response.
4145

42-
The order of MIDDLEWARE_CLASSES is important: the Debug Toolbar middleware
43-
must come after any other middleware that encodes the response's content
44-
(such as GZipMiddleware).
46+
The order of ``MIDDLEWARE_CLASSES`` is important: the Debug Toolbar
47+
middleware must come after any other middleware that encodes the
48+
response's content (such as GZipMiddleware).
4549

46-
Note: The debug toolbar will only display itself if the mimetype of the
47-
response is either `text/html` or `application/xhtml+xml` and contains a
48-
closing `</body>` tag.
50+
**Note**: The debug toolbar will only display itself if the mimetype of the
51+
response is either ``text/html`` or ``application/xhtml+xml`` and contains a
52+
closing ``</body>`` tag.
4953

50-
Note: Be aware of middleware ordering and other middleware that may
51-
intercept requests and return responses. Putting the debug toolbar
54+
**Note**: Be aware of middleware ordering and other middleware that may
55+
intercept requests and return responses. Putting the debug toolbar
5256
middleware *after* the Flatpage middleware, for example, means the
5357
toolbar will not show up on flatpages.
5458

55-
#. Make sure your IP is listed in the `INTERNAL_IPS` setting. If you are
59+
#. Make sure your IP is listed in the ``INTERNAL_IPS`` setting. If you are
5660
working locally this will be::
5761

58-
INTERNAL_IPS = ('127.0.0.1',)
62+
INTERNAL_IPS = ('127.0.0.1',)
5963

60-
Note: This is required because of the built-in requirements of the
61-
`show_toolbar` method. See below for how to define a method to determine
64+
**Note**: This is required because of the built-in requirements of the
65+
``show_toolbar`` method. See below for how to define a method to determine
6266
your own logic for displaying the toolbar.
6367

64-
#. Add `debug_toolbar` to your `INSTALLED_APPS` setting so Django can find the
65-
template files associated with the Debug Toolbar::
68+
#. Add ``debug_toolbar`` to your ``INSTALLED_APPS`` setting so Django can
69+
find the template files associated with the Debug Toolbar::
6670

67-
INSTALLED_APPS = (
68-
...
69-
'debug_toolbar',
70-
)
71-
Alternatively, add the path to the debug toolbar templates
72-
(``'path/to/debug_toolbar/templates'`` to your ``TEMPLATE_DIRS`` setting.)
71+
INSTALLED_APPS = (
72+
...
73+
'debug_toolbar',
74+
)
7375

7476
Configuration
7577
=============
7678

77-
The debug toolbar has two settings that can be set in `settings.py`:
79+
The debug toolbar has two settings that can be set in ``settings.py``:
7880

79-
#. Optional: Add a tuple called `DEBUG_TOOLBAR_PANELS` to your ``settings.py``
81+
#. Optional: Add a tuple called ``DEBUG_TOOLBAR_PANELS`` to your ``settings.py``
8082
file that specifies the full Python path to the panel that you want included
81-
in the Toolbar. This setting looks very much like the `MIDDLEWARE_CLASSES`
82-
setting. For example::
83-
84-
DEBUG_TOOLBAR_PANELS = (
85-
'debug_toolbar.panels.version.VersionDebugPanel',
86-
'debug_toolbar.panels.timer.TimerDebugPanel',
87-
'debug_toolbar.panels.settings_vars.SettingsVarsDebugPanel',
88-
'debug_toolbar.panels.headers.HeaderDebugPanel',
89-
'debug_toolbar.panels.request_vars.RequestVarsDebugPanel',
90-
'debug_toolbar.panels.template.TemplateDebugPanel',
91-
'debug_toolbar.panels.sql.SQLDebugPanel',
92-
'debug_toolbar.panels.signals.SignalDebugPanel',
93-
'debug_toolbar.panels.logger.LoggingPanel',
94-
)
83+
in the Toolbar. This setting looks very much like the ``MIDDLEWARE_CLASSES``
84+
setting. For example::
85+
86+
DEBUG_TOOLBAR_PANELS = (
87+
'debug_toolbar.panels.version.VersionDebugPanel',
88+
'debug_toolbar.panels.timer.TimerDebugPanel',
89+
'debug_toolbar.panels.settings_vars.SettingsVarsDebugPanel',
90+
'debug_toolbar.panels.headers.HeaderDebugPanel',
91+
'debug_toolbar.panels.request_vars.RequestVarsDebugPanel',
92+
'debug_toolbar.panels.template.TemplateDebugPanel',
93+
'debug_toolbar.panels.sql.SQLDebugPanel',
94+
'debug_toolbar.panels.signals.SignalDebugPanel',
95+
'debug_toolbar.panels.logger.LoggingPanel',
96+
)
9597

9698
You can change the ordering of this tuple to customize the order of the
97-
panels you want to display, or add/remove panels. If you have custom panels
99+
panels you want to display, or add/remove panels. If you have custom panels
98100
you can include them in this way -- just provide the full Python path to
99101
your panel.
100102

101103
#. Optional: There are a few configuration options to the debug toolbar that
102-
can be placed in a dictionary:
104+
can be placed in a dictionary called ``DEBUG_TOOLBAR_CONFIG``:
103105

104-
* `INTERCEPT_REDIRECTS`: If set to True (default), the debug toolbar will
106+
* ``INTERCEPT_REDIRECTS``
107+
108+
If set to True (default), the debug toolbar will
105109
show an intermediate page upon redirect so you can view any debug
106-
information prior to redirecting. This page will provide a link to the
107-
redirect destination you can follow when ready. If set to False, redirects
110+
information prior to redirecting. This page will provide a link to the
111+
redirect destination you can follow when ready. If set to False, redirects
108112
will proceed as normal.
109113

110-
* `SHOW_TOOLBAR_CALLBACK`: If not set or set to None, the debug_toolbar
114+
* ``SHOW_TOOLBAR_CALLBACK``
115+
116+
If not set or set to None, the debug_toolbar
111117
middleware will use its built-in show_toolbar method for determining whether
112-
the toolbar should show or not. The default checks are that DEBUG must be
113-
set to True or the IP of the request must be in INTERNAL_IPS. You can
118+
the toolbar should show or not. The default checks are that DEBUG must be
119+
set to True or the IP of the request must be in INTERNAL_IPS. You can
114120
provide your own method for displaying the toolbar which contains your
115-
custom logic. This method should return True or False.
121+
custom logic. This method should return True or False.
122+
123+
* ``EXTRA_SIGNALS``
116124

117-
* `EXTRA_SIGNALS`: An array of custom signals that might be in your project,
125+
An array of custom signals that might be in your project,
118126
defined as the python path to the signal.
119127

120-
* `HIDE_DJANGO_SQL`: If set to True (the default) then code in Django itself
128+
* ``HIDE_DJANGO_SQL``
129+
130+
If set to True (the default) then code in Django itself
121131
won't be shown in SQL stacktraces.
122132

123-
* `SHOW_TEMPLATE_CONTEXT`: If set to True (the default) then a template's
124-
context will be included with it in the Template debug panel. Turning this
133+
* ``SHOW_TEMPLATE_CONTEXT``
134+
135+
If set to True (the default) then a template's
136+
context will be included with it in the Template debug panel. Turning this
125137
off is useful when you have large template contexts, or you have template
126138
contexts with lazy datastructures that you don't want to be evaluated.
127139

128-
* `TAG`: If set, this will be the tag to which debug_toolbar will attach the
140+
* ``TAG``
141+
142+
If set, this will be the tag to which debug_toolbar will attach the
129143
debug toolbar. Defaults to 'body'.
130144

131-
* `ENABLE_STACKTRACES`: If set, this will show stacktraces for SQL queries
145+
* ``ENABLE_STACKTRACES``
146+
147+
If set, this will show stacktraces for SQL queries
132148
and cache calls. Enabling stacktraces can increase the CPU time used when
133149
executing queries. Defaults to True.
134150

135151
Example configuration::
136152

137-
def custom_show_toolbar(request):
138-
return True # Always show toolbar, for example purposes only.
139-
140-
DEBUG_TOOLBAR_CONFIG = {
141-
'INTERCEPT_REDIRECTS': False,
142-
'SHOW_TOOLBAR_CALLBACK': custom_show_toolbar,
143-
'EXTRA_SIGNALS': ['myproject.signals.MySignal'],
144-
'HIDE_DJANGO_SQL': False,
145-
'TAG': 'div',
146-
'ENABLE_STACKTRACES' : True,
147-
}
148-
149-
#. note: HTML page (your templates) must contain closed body tag, meta tag with content="text/html.
150-
toolbar wont display itself in other pages
153+
def custom_show_toolbar(request):
154+
return True # Always show toolbar, for example purposes only.
155+
156+
DEBUG_TOOLBAR_CONFIG = {
157+
'INTERCEPT_REDIRECTS': False,
158+
'SHOW_TOOLBAR_CALLBACK': custom_show_toolbar,
159+
'EXTRA_SIGNALS': ['myproject.signals.MySignal'],
160+
'HIDE_DJANGO_SQL': False,
161+
'TAG': 'div',
162+
'ENABLE_STACKTRACES' : True,
163+
}
164+
165+
``debugsqlshell``
166+
=================
151167

152-
`debugsqlshell`
153-
===============
154168
The following is sample output from running the `debugsqlshell` management
155-
command. Each ORM call that results in a database query will be beautifully
169+
command. Each ORM call that results in a database query will be beautifully
156170
output in the shell::
157171

158172
$ ./manage.py debugsqlshell

0 commit comments

Comments
 (0)