Migrate Markdown docs to ReST and general documentation improvements. (…

…#311)
getsentry · Feb 17, 2017 · 775916b · 775916b
1 parent 72ec8dc
commit 775916b
Show file tree

Hide file tree

Showing 20 changed files with 1,360 additions and 1,908 deletions.
diff --git a/README.md b/README.md
diff --git a/docs/config.rst b/docs/config.rst
diff --git a/docs/index.rst b/docs/index.rst
@@ -1,6 +1,6 @@
 .. sentry:edition:: self
 
-    Raven-Java
+    Raven Java
     ==========
 
 .. sentry:edition:: on-premise, hosted
@@ -10,23 +10,23 @@
     Java
     ====
 
-Raven is the Java client for Sentry. Raven relies on the most popular
-logging libraries to capture and convert logs before sending details to a
-Sentry instance.
-
-While it's strongly recommended to use one of the supported logging
-frameworks to capture and send messages to Sentry, a it is possible to do
-so manually with the main project raven.
+Raven for Java (``raven-java``) is the official Java client for Sentry. At its core it provides
+a raw client for sending events to Sentry, but it is highly recommended that you
+use one of the included library or framework integrations listed below if at all possible.
 
 .. toctree::
-   :maxdepth: 2
-   :titlesonly:
+    :maxdepth: 2
+    :titlesonly:
 
-   installation
-   config
-   modules/index
+    config
+    usage
+    modules/index
 
 Resources:
 
+* `Documentation <https://docs.sentry.io/clients/java/>`_
 * `Bug Tracker <http://github.com/getsentry/raven-java/issues>`_
-* `Github Project <http://github.com/getsentry/raven-java>`_
+* `Code <http://github.com/getsentry/raven-java>`_
+* `Mailing List <https://groups.google.com/group/getsentry>`_
+* `IRC <irc://irc.freenode.net/sentry>`_  (irc.freenode.net, #sentry)
+* `Travis CI <http://travis-ci.org/getsentry/raven-java>`_
diff --git a/docs/installation.rst b/docs/installation.rst
diff --git a/docs/modules/android.rst b/docs/modules/android.rst
@@ -0,0 +1,63 @@
+Android
+=======
+
+Installation
+------------
+
+Using Gradle (Android Studio) in your ``app/build.gradle`` add:
+
+.. sourcecode:: groovy
+
+    compile 'com.getsentry.raven:raven-android:7.8.2'
+
+For other dependency managers see the `central Maven repository <https://search.maven.org/#artifactdetails%7Ccom.getsentry.raven%7Craven-android%7C7.8.2%7Cjar>`_.
+
+Usage
+-----
+
+Configure your Sentry DSN (client key) in your ``AndroidManifest.xml``:
+
+.. sourcecode:: xml
+
+    <application>
+      <meta-data
+        android:name="com.getsentry.raven.android.DSN"
+        android:value="https://publicKey:secretKey@host:port/1?options" />
+    </application>
+
+Your application must also have permission to access the internet in order to send
+event to the Sentry server. In your ``AndroidManifest.xml``:
+
+.. sourcecode:: xml
+
+    <uses-permission android:name="android.permission.INTERNET" />
+    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
+
+Then, in your application's ``onCreate``, initialize the Raven client:
+
+.. sourcecode:: java
+
+    import com.getsentry.raven.android.Raven;
+
+    // "this" should be a reference to your main Activity
+    Raven.init(this.getApplicationContext());
+
+Now you can use ``Raven`` to capture events anywhere in your application:
+
+.. sourcecode:: java
+
+    // Send a simple event to the Sentry server
+    Raven.capture("Error message");
+
+    try {
+        something()
+    } catch (Exception e) {
+        // Send an exception event to the Sentry server
+        Raven.capture(e);
+    }
+
+    // Or build an event manually
+    EventBuilder eventBuilder = new EventBuilder()
+                                  .withMessage("Exception caught")
+                                  .withLevel(Event.Level.ERROR);
+    Raven.capture(eventBuilder.build());
diff --git a/docs/modules/appengine.rst b/docs/modules/appengine.rst
@@ -1,24 +1,17 @@
 Google App Engine
 =================
 
-The `raven-appengine` module enables the support of the async connections
-in Google App Engine.
+The ``raven-appengine`` library provides `Google App Engine <https://cloud.google.com/appengine/>`_
+support for Raven via the `Task Queue API
+<https://cloud.google.com/appengine/docs/java/taskqueue/>`_.
 
-The project can be found on github: `raven-java/appengine
-<https://github.com/getsentry/raven-java/tree/master/raven-appengine>`_
-
-Google App Engine doesn't support threads but provides instead a
-TaskQueueing system allowing tasks to be run in the background.
-
-This module replaces the async system provided by default with one relying
-on the tasks.
-
-This module is not useful outside of Google App Engine.
+The source can be found `on Github
+<https://github.com/getsentry/raven-java/tree/master/raven-appengine>`_.
 
 Installation
 ------------
 
-If you want to use Maven you can install Raven-AppEngine as dependency:
+Using Maven:
 
 .. sourcecode:: xml
 
@@ -28,25 +21,37 @@ If you want to use Maven you can install Raven-AppEngine as dependency:
         <version>7.8.2</version>
     </dependency>
 
+Using Gradle:
+
+.. sourcecode:: groovy
+
+    compile 'com.getsentry.raven:raven-appengine:7.8.2'
+
+Using SBT:
+
+.. sourcecode:: scala
+
+    libraryDependencies += "com.getsentry.raven" % "raven-appengine" % "7.8.2"
+
+For other dependency managers see the `central Maven repository <https://search.maven.org/#artifactdetails%7Ccom.getsentry.raven%7Craven-appengine%7C7.8.2%7Cjar>`_.
+
 Usage
 -----
 
-This module provides a new ``RavenFactory`` which replaces the default async
-system with a GAE compatible one.
+This module provides a new ``RavenFactory`` implementation which replaces the default async
+system with a Google App Engine compatible one. You'll need to configure Raven to use the
+``com.getsentry.raven.appengine.AppEngineRavenFactory`` as its factory.
 
 The queue size and thread options will not be used as they are specific to
-the default multithreaded system.
-
-It is necessary to force the raven factory name to
-``com.getsentry.raven.appengine.AppEngineRavenFactory``.
+the default Java threading system.
 
 Queue Name
 ----------
 
 By default, the default task queue will be used, but it's possible to
 specify which one will be used with the ``raven.async.gae.queuename`` option::
 
-    ___DSN___?raven.async.gae.queuename=MyQueueName
+    http://public:private@host:port/1?raven.async.gae.queuename=MyQueueName
 
 Connection Name
 ---------------
@@ -55,7 +60,7 @@ As the queued tasks are sent across different instances of the
 application, it's important to be able to identify which connection should
 be used when processing the event. To do so, the GAE module will identify
 each connection based on an identifier either automatically generated or
-user defined. TO manually set the connection identifier (only used
-internally) use the option ``raven.async.connectionid``::
+user defined. To manually set the connection identifier (only used
+internally) use the option ``raven.async.gae.connectionid``::
 
-    ___DSN___?raven.async.gae.connectionid=MyConnection
+    http://public:private@host:port/1?raven.async.gae.connectionid=MyConnection
diff --git a/docs/modules/index.rst b/docs/modules/index.rst
@@ -1,8 +1,8 @@
-Modules
-=======
+Integrations
+============
 
-Raven-Java comes in different modules from low-level access to event
-submission as well as integration into different packages.
+The Raven Java SDK comes with support for some frameworks and libraries so that
+you don't have to capture and send errors manually.
 
 .. toctree::
    :maxdepth: 1
@@ -12,3 +12,4 @@ submission as well as integration into different packages.
    log4j2
    logback
    appengine
+   android