Moved much of the readme into actual documentation

.gitignore

@@ -2,4 +2,5 @@
 *.DS_Store
 *~
 django_debug_logging.egg-info
-dist
+dist
+_build

README.rst

@@ -49,159 +49,12 @@ A log record:
    :alt: Debug Logging detail view
    :target: https://github.com/lincolnloop/django-debug-logging/raw/develop/docs/screenshots/debug_logging_3.png
 
-Prerequisites
--------------
-
-These requirements are installed automatically by *pip* and *easy_install*, and
-are in the included *requirements.pip* file.
-
-`Django Debug Toolbar`_ - This project is designed to work alongside the Django
-Debug Toolbar and extend its functionality to support logging.
-
-Picklefield_ - Used to saved pickled versions of settings, sql queries, and
-cache calls to the database.
-
-Installation
-------------
-
-Before you begin, make sure Django Debug Toolbar is configured and working
-properly.
-
-Install the project with pip::
-
-    $ pip install django-debug-logging
-
-This should install django-picklefield as well, which is needed.
-
-Next, you'll add *debug_logging* to your INSTALLED_APPS::
-
-    INSTALLED_APPS = (
-        ...
-        'debug_toolbar',
-        'debug_logging',
-    )
-
-Now, you'll need to replace the standard DebugToolbarMiddleware with a
-middleware that extends it to add logging functionality.  The toolbar will
-still function normally when logging is disabled.
-
-From your MIDDLEWARE_CLASSES setting, remove::
-
-    'debug_toolbar.middleware.DebugToolbarMiddleware',
-
-Replace it with::
-
-    'debug_logging.middleware.DebugLoggingMiddleware',
-
-Now, you'll need to replace a few of the panels with extended versions that
-support logging.  If you don't want the data from any one of these panels to
-be logged, you can skip it.
-
-From your DEBUG_TOOLBAR_PANELS setting, remove::
-
-    'debug_toolbar.panels.cache.CacheDebugPanel',
-    'debug_toolbar.panels.settings_vars.SettingsVarsDebugPanel',
-    'debug_toolbar.panels.sql.SQLDebugPanel',
-    'debug_toolbar.panels.timer.TimerDebugPanel',
-
-Replace them with::
-
-    'debug_logging.panels.cache.CacheLoggingPanel',
-    'debug_logging.panels.settings_vars.SettingsVarsLoggingPanel',
-    'debug_logging.panels.sql.SQLLoggingPanel',
-    'debug_logging.panels.timer.TimerLoggingPanel',
-
-There are also a couple of panels that are unique to Django Debug Logging that
-you may find convenient when logging data over time.  If you'd like, you can
-add them to your DEBUG_TOOLBAR_PANELS setting::
-
-    'debug_logging.panels.revision.RevisionLoggingPanel',
-    'debug_logging.panels.identity.IdentityLoggingPanel',
-
-Add the debug logging urls to your urls.py::
-
-    urlpatterns = patterns('',
-        ...
-        url(r'^debug-logging/', include('debug_logging.urls')),
-    )
-    
-The Debug Logger will ignore requests made to this frontend interface, so your
-log won't be clogged with information you have no use for.
-
-Finally, run syncdb to create the models for statistic logging::
-
-    $ python manage.py syncdb
-
-South migrations are included in case migrations are needed when upgrading to
-new versions.
-
-Requests are logged when they contain a 'DJANGO_DEBUG_LOGGING' header set to
-True.  This header is added automatically by the 'log_urls' command when it is
-used.  To prevent any performance impact from the rendering of the Debug Toolbar, it
-is not shown when this header is present.
-
-For the best results, don't use the site while a test run is in progress.
-
-Settings
---------
-
-* ``SQL_EXTRA``: This setting determines whether the full details of each query
-  are logged, or just the number of queries and the total time.  It defaults to
-  ``False``.
-
-* ``CACHE_EXTRA``: This determines whether the full details of each cache call
-  are logged, or just the summary details. It defaults to `` False``.
-
-* ``BLACKLIST``: Add a list of url prefixes that you would like to exclude from
-  logging here.  The url for the Debug Logging frontend interface is added to
-  this blacklist automatically.
-
-Running a Url Test
-------------------
-
-A management command is included that uses the test client to hit a list of
-urls in sequence, allowing them to be logged to the database.  To use it, first
-create a list of urls with a new url on each line.  Lines beginning with # are
-ignored. ::
-    
-    # Main urls
-    /
-    /my/url/
-    /my/other/url/
-    # Comments
-    /my/comment/url/
-
-Then, enable logging and run the *log_urls* management command::
-
-    $ python manage.py log_urls myapp/my_urls.txt
-
-Unless it is run with a verbosity of 0 the command will output status
-messages, such as urls that return codes other than 200 and urls that raise
-errors.
-
-To run the test as an authenticated user, use the username and password
-options::
-
-    $ python manage.py log_urls my_urls.txt --username Legen --password dary
-
-You can also add a name and a description to your run, if you'd like::
-
-    $ python manage.py log_urls my_urls.txt --name "Admin Urls" --description "Urls used by site admins"
-
-If you'd like to conduct a test run with a tool other than the log_urls
-management command, you can use the command to manually start and end TestRun
-objects, so that your results will be organized correctly in the UI. Before you
-conduct your test, simply run::
-
-    $ python manage.py log_urls --manual-start
-
-Then, when you are finished hitting your desired urls::
-
-    $ python manage.py log_urls --manual-end
-
 To Do
 -----
 
+We welcome contributions!  Here are some of our main priorities for continued
+development:
+
 * Add a --repeat option to the log_urls command so that the urls can be run
   through multiple times.
 

docs/Makefile

@@ -0,0 +1,130 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = _build
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  dirhtml    to make HTML files named index.html in directories"
+	@echo "  singlehtml to make a single large HTML file"
+	@echo "  pickle     to make pickle files"
+	@echo "  json       to make JSON files"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  qthelp     to make HTML files and a qthelp project"
+	@echo "  devhelp    to make HTML files and a Devhelp project"
+	@echo "  epub       to make an epub"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  text       to make text files"
+	@echo "  man        to make manual pages"
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+	-rm -rf $(BUILDDIR)/*
+
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+json:
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/django-debug-logging.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/django-debug-logging.qhc"
+
+devhelp:
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	@echo
+	@echo "Build finished."
+	@echo "To view the help file:"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/django-debug-logging"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/django-debug-logging"
+	@echo "# devhelp"
+
+epub:
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
+	      "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+changes:
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."