Updated raven-js docs to have more on the index page.

Author: mitsuhiko

docs/config.rst

@@ -1,9 +1,9 @@
 Configuration
 =============
 
-We must first configure Sentry to allow certain hosts to report errors.
-This prevents abuse so somebody else couldn't start sending errors to your
-account from their site.
+We must first configure the client to allow certain hosts to report
+errors.  This prevents abuse so somebody else couldn't start sending
+errors to your account from their site.
 
 **Note**: Without setting this, all messages will be rejected!
 

docs/index.rst

@@ -15,6 +15,88 @@ used to report errors from browser and node environments.  The quality
 of reporting will heavily depend on the environment the data is submitted
 from.
 
+Installation
+------------
+
+Raven.js is distributed in a few different methods, and should get
+included after any other libraries are included, but before your own
+scripts.  For all details see :doc:`install`.  For just getting started,
+you can use our CDN:
+
+.. sourcecode:: html
+
+    <script src="//cdn.ravenjs.com/1.1.19/raven.min.js"></script>
+
+Configuring the Client
+----------------------
+
+We must first configure Sentry to allow certain hosts to report errors.
+This prevents abuse so somebody else couldn't start sending errors to your
+account from their site.  This can be found under the *Project Details*
+page in Sentry.
+
+Now need to set up Raven.js to use your Sentry DSN:
+
+.. code-block:: javascript
+
+    Raven.config('___PUBLIC_DSN___').install()
+
+At this point, Raven is ready to capture any uncaught exception.
+
+Although, this technically works, this is not going to yield the greatest
+results.  It's highly recommended to next check out :doc:`config` and
+:doc:`usage` after you have it up and running to improve your results.
+
+Reporting Errors
+----------------
+
+The simplest way, is to try and explicitly capture and report potentially
+problematic code with a ``try...catch`` block and
+``Raven.captureException``.
+
+.. code-block:: javascript
+
+    try {
+        doSomething(a[0])
+    } catch(e) {
+        Raven.captureException(e)
+    }
+
+There are more ways to report errors.  For a complete guide on this see
+:ref:`raven-js-reporting-errors`.
+
+Tracking Users
+--------------
+
+While a user is logged in, you can tell Sentry to associate errors with
+user data.  This data is then submitted with each error which allows you
+to figure out which users are affected.
+
+.. code-block:: javascript
+
+    Raven.setUserContext({
+        email: '[email protected]',
+        id: '123'
+    })
+
+If at any point, the user becomes unauthenticated, you can call
+``Raven.setUserContext()`` with no arguments to remove their data.
+
+Dealing with Minified Source Code
+---------------------------------
+
+Raven and Sentry support `Source Maps
+<http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/>`_.  If
+you provide source maps in addition to your minified files that data
+becomes available in Sentry.  For more information see
+:ref:`raven-js-sourcemaps`.
+
+Deep Dive
+---------
+
+For more detailed information about how to get most out of Raven.js there
+is additional documentation available that covers all the rest:
+
 .. toctree::
    :maxdepth: 2
    :titlesonly:

docs/install.rst

@@ -9,7 +9,7 @@ So for example:
 .. sourcecode:: html
 
     <script src="jquery.js"></script>
-    <script src="//cdn.ravenjs.com/1.1.18/jquery,native/raven.min.js"></script>
+    <script src="//cdn.ravenjs.com/1.1.19/jquery,native/raven.min.js"></script>
     <script>Raven.config('___PUBLIC_DSN___').install();</script>
     <script src="app.js"></script>
 
@@ -28,7 +28,7 @@ Our CDN distributes builds with and without :doc:`plugins <plugins>`.
 
 .. sourcecode:: html
 
-    <script src="//cdn.ravenjs.com/1.1.18/raven.min.js"></script>
+    <script src="//cdn.ravenjs.com/1.1.19/raven.min.js"></script>
 
 **We highly recommend trying out a plugin or two since it'll greatly
 improve the chances that we can collect good information.**

docs/usage.rst

@@ -7,6 +7,8 @@ meaningful stack traces, but browsers make it pretty difficult.
 The easiest solution is to prevent an error from bubbling all of the way
 up the stack to ``window``.
 
+.. _raven-js-reporting-errors:
+
 Reporting Errors Correctly
 --------------------------
 
@@ -82,6 +84,9 @@ If at any point, the user becomes unauthenticated, you can call
 would only really be useful in a large web app where the user logs in/out
 without a page reload.*
 
+This data is generally submitted with each error or message and allows you
+to figure out which errors are affected by problems.
+
 Capturing Messages
 ------------------
 
@@ -151,10 +156,12 @@ is already initialized:
     Raven.isSetup()
 
 
-Dealing with minified source code
+.. _raven-js-source-maps:
+
+Dealing with Minified Source Code
 ---------------------------------
 
-Raven and Sentry now support `Source Maps
+Raven and Sentry support `Source Maps
 <http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/>`_.
 
 We have provided some instructions to creating Source Maps over at