Updated sourcemap document and fixed interlinks.

Author: mitsuhiko

docs/sourcemaps.rst

@@ -1,38 +1,49 @@
-.. _sourcemaps:
+.. _raven-js-sourcemaps:
 
 Source Maps
 ===========
 
-In various browsers Sentry supports deminifying JavaScript via source maps. A source map is a file generated
-by your minifier which compresses a mapping of the minified file to the original uncompressed version(s).
+In various browsers Sentry supports deminifying JavaScript via source
+maps. A source map is a file generated by your minifier which compresses a
+mapping of the minified file to the original uncompressed version(s).
 
-One important thing to note is that even though we support mapping files, a users browser may not actually be able
-to collect the required information for the server to generate a sourcemap.
+One important thing to note is that even though we support mapping files,
+a users browser may not actually be able to collect the required
+information for the server to generate a sourcemap.
 
 Sentry requires the following to be able to map tracebacks to their source:
 
 * A source map header or footer
 * A publicly accessible uncompressed version of the source
 * A line of context that includes a line number, column number, and filename
 
-The first two items are the responsibility of you, the end-user, and you can take care of publishing them as part
-of your build process. The latter however, with an individual line of context, is severely crippled in many browsers.
+The first two items are the responsibility of you, the end-user, and you
+can take care of publishing them as part of your build process. The latter
+however, with an individual line of context, is severely crippled in many
+browsers.
 
-One thing to note is that Sentry will attempt to process the source map before storing (or grouping) an event. This ensures that if we are
-able to deminify the source, we'll be able to more effectively group similar events over time.</p>
+One thing to note is that Sentry will attempt to process the source map
+before storing (or grouping) an event. This ensures that if we are able to
+deminify the source, we'll be able to more effectively group similar
+events over time.</p>
 
 Browser Support
 ---------------
 
-In our experiences, the only browser that routinely delivers usable error reports is **Google Chrome**.
+In our experiences, the only browser that routinely delivers usable error
+reports is **Google Chrome**.
 
-For additional information, see this more up-to-date `wiki page <https://github.com/ryanseddon/source-map/wiki/Source-maps:-languages,-tools-and-other-inf>`_.
+For additional information, see this more up-to-date `wiki page
+<https://github.com/ryanseddon/source-map/wiki/Source-maps:-languages,-tools-and-other-inf>`_.
 
 Generating a Source Map
 -----------------------
 
-While there are several compression libraries which support source maps, as of writing our recommendation is to use
-`UglifyJS <https://github.com/mishoo/UglifyJS2>`_. That said, many tools such as `webpack <http://webpack.github.io/>`_ and `browserify <http://browserify.org/>`_.
+While there are several compression libraries which support source maps,
+as of writing our recommendation is to use `UglifyJS
+<https://github.com/mishoo/UglifyJS2>`_. That said, many tools such as
+`webpack <http://webpack.github.io/>`_ and `browserify
+<http://browserify.org/>`_.
 
 As an example, we can look at how we used to do things with Sentry (pre-webpack):
 
@@ -43,30 +54,38 @@ As an example, we can look at how we used to do things with Sentry (pre-webpack)
       --source-map-url={name}.map.js \
       --source-map={relpath}/{name}.map.js -o {output}
 
-We won't attempt to go into the complexities of source maps, so we recommend taking a stab at compiling them, and running them against a validator.
+We won't attempt to go into the complexities of source maps, so we
+recommend taking a stab at compiling them, and running them against a
+validator.
 
 Validating a Source Map
 -----------------------
 
-We maintain an online validation tool that can be used to test your source (and sourcemaps) against: `sourcemaps.io <http://sourcemaps.io>`_.
+We maintain an online validation tool that can be used to test your source
+(and sourcemaps) against: `sourcemaps.io <http://sourcemaps.io>`_.
 
 Uploading SourceMaps to Sentry
 ------------------------------
 
-In many cases your application may sit behind firewalls or you simply can't expose source code to the public. Sentry provides an abstraction called
-**Releases** which you can attach source artifacts to.
+In many cases your application may sit behind firewalls or you simply
+can't expose source code to the public. Sentry provides an abstraction
+called **Releases** which you can attach source artifacts to.
 
-The release API is intended to allow you to store source files (and sourcemaps) within Sentry. This removes the requirement for them to be
-web-accessible, and also removes any inconsistency that could come from network flakiness (on either your end, or Sentry's end).
-
-* Start by creating a new API key under your organization's API Keys nav (on the home).
+The release API is intended to allow you to store source files (and
+sourcemaps) within Sentry. This removes the requirement for them to be
+web-accessible, and also removes any inconsistency that could come from
+network flakiness (on either your end, or Sentry's end).
 
+* Start by creating a new API key under your organization's API Keys nav
+  (on the home).
 * Ensure you you have ``project:write`` selected under scopes.
+* You'll use HTTP basic auth with the api key being your username, and an
+  empty value for the password.
 
-* You'll use HTTP basic auth with the api key being your username, and an empty value for the password.
-
-Now you need to setup your build system to create a release, and attach the various source files. You will want to upload all dist
-files (i.e. the minified/shipped JS), the referenced sourcemaps, and the files that those sourcemaps point to.
+Now you need to setup your build system to create a release, and attach
+the various source files. You will want to upload all dist files (i.e. the
+minified/shipped JS), the referenced sourcemaps, and the files that those
+sourcemaps point to.
 
 .. code-block:: bash
 
@@ -111,22 +130,28 @@ files (i.e. the minified/shipped JS), the referenced sourcemaps, and the files t
       -u [api_key]: \
       -X DELETE
 
-Additionally, you'll need to configure [raven-js](https://github.com/getsentry/raven-js) to send the ``release``:
+Additionally, you'll need to configure
+[raven-js](https://github.com/getsentry/raven-js) to send the ``release``:
 
 .. code-block:: javascript
 
     Raven.config({
         release: '2da95dfb052f477380608d59d32b4ab9'
     });
 
-Note: You dont *have* to upload the source files (ref'd by sourcemaps), but without them the grouping algorithm will not be as strong, and the UI will not show any contextual source.
+Note: You dont *have* to upload the source files (ref'd by sourcemaps),
+but without them the grouping algorithm will not be as strong, and the UI
+will not show any contextual source.
 
-Additional information can be found in the `Releases API documentation <https://app.getsentry.com/docs/api/releases/>`_.
+Additional information can be found in the `Releases API documentation
+<https://app.getsentry.com/docs/api/releases/>`_.
 
 .. sentry:edition:: hosted
 
     Working Behind a Firewall
     -------------------------
 
-    While the recommended solution is to upload your source artifacts to Sentry, sometimes its nescessary to allow communication from Sentry's internal IPs. To
-    work around this you can whitelist our :doc:`IP Ranges <../../ip-ranges>`.
+    While the recommended solution is to upload your source artifacts to
+    Sentry, sometimes its nescessary to allow communication from Sentry's
+    internal IPs. To work around this you can whitelist our :doc:`IP
+    Ranges <../../ip-ranges>`.