more docs

docs/configuration.rst

@@ -0,0 +1,55 @@
+Configuration
+======
+
+Authentication/Authorisation
+----
+
+By default anybody can access the Silk user interface by heading to `/silk/`. To enable your Django 
+auth backend place the following in `settings.py`:
+
+
+.. code-block:: python
+
+	SILKY_AUTHENTICATION = True  # User must login
+	SILKY_AUTHORISATION = True  # User must have permissions
+
+If ``SILKY_AUTHORISATION`` is ``True``, by default Silk will only authorise users with ``is_staff`` attribute set to ``True``.
+
+You can customise this using the following in ``settings.py``:
+
+.. code-block:: python
+
+	def my_custom_perms(user):
+	    return user.is_allowed_to_use_silk
+
+	SILKY_PERMISSIONS = my_custom_perms
+
+
+Request/Response bodies
+----
+
+By default, Silk will save down the request and response bodies for each request for future viewing
+no matter how large. If Silk is used in production under heavy volume with large bodies this can have
+a huge impact on space/time performance. This behaviour can be configured with following options:
+
+.. code-block:: python
+
+	SILKY_MAX_REQUEST_BODY_SIZE = -1  # Silk takes anything <0 as no limit
+	SILKY_MAX_RESPONSE_BODY_SIZE = 1024  # If response body>1024kb, ignore
+
+
+Meta-Profiling
+-----
+
+Sometimes its useful to be able to see what effect Silk is having on the request/response time. To do this add
+the following to your `settings.py`:
+
+.. code-block:: python
+
+	SILKY_META = True
+
+Silk will then record how long it takes to save everything down to the database at the end of each request:
+
+.. image:: meta.png
+
+Note that in the above screenshot, this means that the request took 29ms (22ms from Django and 7ms from Silk)

docs/index.rst

@@ -11,6 +11,8 @@ Silk
 
    quickstart
    profiling
+   configuration
+   troubleshooting
 
 Silk is a live profiling and inspection tool for the Django framework. Silk intercepts and stores HTTP requests and database queries before presenting them in a user interface for further inspection..
 

docs/profiling.rst

@@ -106,6 +106,7 @@ Note that dynamic profiling behaves in a similar fashion to that of the python m
 we modify the function in-place e.g:
 
 .. code-block:: python
+
 	""" my.module """
 	from another.module import foo
 
@@ -114,13 +115,13 @@ we modify the function in-place e.g:
 	# ...do some other stuff
 
 
-,we would profile ``foo`` by dynamically decorating `my.module.foo` as opposed to ``another.module.foo``:
+We would profile ``foo`` by dynamically decorating `my.module.foo` as opposed to ``another.module.foo``:
 
 .. code-block:: python
+
 	SILKY_DYNAMIC_PROFILING = [{
 	    'module': 'my.module',
 	    'function': 'foo'
 	}]
 
-If we were to apply the dynamic profile to the functions source module ``another.module.foo`` *after*
-it has already been imported, no profiling would be triggered.
+If we were to apply the dynamic profile to the functions source module ``another.module.foo`` *after* it has already been imported, no profiling would be triggered.

docs/quickstart.rst

@@ -1,2 +1,54 @@
 Quick Start
 ===========
+
+Silk is installed like any other Django app.
+
+First install via pip:
+
+.. code-block:: bash
+
+	pip install django-silk
+
+Add the following to your ``settings.py``:
+
+.. code-block:: python
+	
+	MIDDLEWARE_CLASSES = ( 
+	    ...
+	    'silk.middleware.SilkyMiddleware',
+	    ...
+	)
+
+	INSTALLED_APPS = (
+	    ...
+	    'silk'
+	)
+
+Add the following to your ``urls.py``:
+
+.. code-block:: python
+	
+	urlpatterns += patterns('', url(r'^silk', include('silk.urls', namespace='silk')))
+
+Run ``syncdb`` to create Silk's database tables:
+
+.. code-block:: python
+
+    python manage.py syncdb
+
+And voila! Silk will begin intercepting requests and queries which you can inspect by visiting ``/silk/``
+
+Other Installation Options
+-------
+
+You can download a release from `github <https://github.com/mtford90/silk/releases>`_ and then install using pip:
+
+.. code-block:: bash
+
+	pip install django-silk-<version>.tar.gz
+
+You can also install directly from the github repo but please note that this version is not guaranteed to be working:
+
+.. code-block:: bash
+
+	pip install -e git+https://github.com/mtford90/silk.git#egg=silk

docs/troubleshooting.rst

@@ -0,0 +1,26 @@
+Troubleshooting
+==========
+
+The below details common problems when using Silk, most of which have been derived from the solutions to github issues.
+
+Unicode
+------
+
+Silk saves down the request and response bodies of each HTTP request by default. These bodies are often UTF encoded and hence it is important that Silk's database tables are also UTF encoded. Django has no facility for enforcing this and instead assumes that the configured database defaults to UTF.
+
+If you see errors like:
+
+
+	Incorrect string value: '\xCE\xBB, \xCF\x86...' for column 'raw_body' at row...
+
+
+Then it's likely your database is not configured correctly for UTF encoding.
+
+See this `github issue <https://github.com/mtford90/silk/issues/21>`_ for more details and workarounds.
+
+Middleware
+------
+
+The middleware is placement sensitive. If the middleware before ``silk.middleware.SilkyMiddleware`` returns from ``process_request`` then ``SilkyMiddleware`` will never get the chance to execute. Therefore you must ensure that any middleware placed before never returns anything from ``process_request``. See the `django docs <https://docs.djangoproject.com/en/dev/topics/http/middleware/#process-request>`_ for more information on this.
+
+This `GitHub issue <https://github.com/mtford90/silk/issues/12>`_ also has information on dealing with middleware problems.