From d055e8663729d8c00c9eb073ae232bc94f732412 Mon Sep 17 00:00:00 2001 From: Armin Ronacher Date: Mon, 27 Aug 2018 23:56:00 +0200 Subject: [PATCH] ref: Kill in-repo docs --- docs/index.rst | 160 ------------------------------------ docs/ionic.rst | 80 ------------------ docs/sentry-doc-config.json | 14 ---- 3 files changed, 254 deletions(-) delete mode 100644 docs/index.rst delete mode 100644 docs/ionic.rst delete mode 100644 docs/sentry-doc-config.json diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index b476922..0000000 --- a/docs/index.rst +++ /dev/null @@ -1,160 +0,0 @@ -.. class:: platform-cordova - -.. _cordova: - -Cordova -======= - -This is the documentation for our Cordova SDK. The SDK uses a native extension -for iOS and Android but will fall back to a pure JavaScript version (@sentry/browser) if needed. - -Installation ------------- - -Start by adding Sentry and then linking it:: - - $ cordova plugin add sentry-cordova - -`Sentry Wizard `_ will help you to configure -your project. We also add a build step to your Xcode project to upload debug -symbols we need to symbolicate iOS crashes. - -Configuration -------------- - -You have to whitelist ``sentry.io`` in your ``config.xml`` like: - - - -Keep in mind if you use an on-premise installation, adjust this domain accordingly. - -This example shows the bare minimum for a plain Cordova project. -Add this to you `index.js`: - -.. code-block:: javascript - - onDeviceReady: function() { - ... - var Sentry = cordova.require("sentry-cordova.Sentry"); - Sentry.init({ dsn: '___PUBLIC_DSN___' }); - ... - } - -This will setup the Client for native and JavaScript crashes. -If you minify or bundle your code we need your sourcemap files in order to symbolicate -JavaScript errors, please see: `JavaScript sourcemaps `_ -for more details. - -Usage ------ - -* capturing messages and error: - - .. sourcecode:: javascript - - Sentry.captureMessage('message'); - try { - myFailingFunction(); - } catch (e) { - Sentry.captureException(e); - } - - -Note that we will track unhandled errors and promises by default. - -* adding breadcrumbs: - - .. sourcecode:: javascript - - Sentry.addBreadcrumb({ message: 'message' }); - - -* context handling: - - .. sourcecode:: javascript - - Sentry.configureScope(scope => { - scope.setUser({ id: '123', email: 'test@sentry.io', username: 'sentry' }); - scope.setTag('cordova', 'true'); - scope.setExtra('myData', ['1', 2, '3']); - }); - - -iOS Specifics -------------- - -When you use Xcode you can hook directly into the build process to upload -debug symbols. If you however are using bitcode you will -need to disable the "Upload Debug Symbols to Sentry" build phase and then -separately upload debug symbols from iTunes Connect to Sentry. - -Run Script Phase ----------------- - -.. admonition:: Note - - If the wizard ran successfully, it should have done setup all the necessary steps for you. - You can still check if everything was setup correctly. - -If you want to run the debug symbol upload during building your app. You can add this as a -run script phase in Xcode. Also make sure to set the ``DEBUG_INFORMATION_FORMAT`` in your -project settings to ``DWARF and dSYM file``. - - .. sourcecode:: bash - - export SENTRY_PROPERTIES=sentry.properties - function getProperty { - PROP_KEY=$1 - PROP_VALUE=`cat $SENTRY_PROPERTIES | grep "$PROP_KEY" | cut -d'=' -f2` - echo $PROP_VALUE - } - if [ ! -f $SENTRY_PROPERTIES ]; then - echo "warning: SENTRY: sentry.properties file not found! Skipping symbol upload." - exit 0 - fi - echo "# Reading property from $SENTRY_PROPERTIES" - SENTRY_CLI=$(getProperty "cli.executable") - SENTRY_COMMAND="../../$SENTRY_CLI upload-dsym" - $SENTRY_COMMAND - -The next script makes sure that all unnes architectures are strip from you binary when -submitting the build to iTunes Connect. - -.. admonition:: Note - - If you are getting an error while submitting your build to iTunes Connect, this script - is probably missing. Also readding the plugin helped some people. - - .. sourcecode:: bash - - # SENTRY_FRAMEWORK_PATCH - APP_PATH="${TARGET_BUILD_DIR}/${WRAPPER_NAME}" - find "$APP_PATH" -name '*.framework' -type d | while read -r FRAMEWORK - do - FRAMEWORK_EXECUTABLE_NAME=$(defaults read "$FRAMEWORK/Info.plist" CFBundleExecutable) - FRAMEWORK_EXECUTABLE_PATH="$FRAMEWORK/$FRAMEWORK_EXECUTABLE_NAME" - echo "Executable is $FRAMEWORK_EXECUTABLE_PATH" - EXTRACTED_ARCHS=() - - for ARCH in $ARCHS - do - echo "Extracting $ARCH from $FRAMEWORK_EXECUTABLE_NAME" - lipo -extract "$ARCH" "$FRAMEWORK_EXECUTABLE_PATH" -o "$FRAMEWORK_EXECUTABLE_PATH-$ARCH" - EXTRACTED_ARCHS+=("$FRAMEWORK_EXECUTABLE_PATH-$ARCH") - done - - echo "Merging extracted architectures: ${ARCHS}" - lipo -o "$FRAMEWORK_EXECUTABLE_PATH-merged" -create "${EXTRACTED_ARCHS[@]}" - rm "${EXTRACTED_ARCHS[@]}" - echo "Replacing original executable with thinned version" - rm "$FRAMEWORK_EXECUTABLE_PATH" - mv "$FRAMEWORK_EXECUTABLE_PATH-merged" "$FRAMEWORK_EXECUTABLE_PATH" - done - -Deep Dive ---------- - -.. toctree:: - :maxdepth: 2 - - ionic diff --git a/docs/ionic.rst b/docs/ionic.rst deleted file mode 100644 index e13ff97..0000000 --- a/docs/ionic.rst +++ /dev/null @@ -1,80 +0,0 @@ -Using Sentry with Ionic ------------------------ - -To use Sentry with `Ionic `_ you have to add -`sentry-cordova` as a depenendcy to you package.json. - - -First run ``npm i --save sentry-cordova`` and make sure you already added the -the platfroms you want to support with ``ionic cordova platform add ios`` and/or -``ionic cordova platform add android``. - - -After that it's important to run ``cordova plugin add sentry-cordova`` -without the ionic wrapper. - -.. admonition:: Warning - - Do not run ``ionic cordova plugin add sentry-cordova``. - The ionic cli wrapper sucks up all the input and sentry-wizard will not be able - to setup your project. - -When building your app with ionic for production make sure you have sourcemaps enabled. -You have to add this to your ``package.json``: - -.. code-block:: javascript - - "config": { - "ionic_generate_source_map": "true" - } - -Otherwise we are not able to upload sourcemaps to Sentry. - -.. admonition:: Warning - - If you want to skip the automatic release version and set the release completly - for yourself. You have to add this env var to disable it e.g.: - ``SENTRY_SKIP_AUTO_RELEASE=true ionic cordova emulate ios --prod`` - -To setup Sentry in your codebase add this to your ``app.module.ts``: - -.. code-block:: javascript - - import * as Sentry from 'sentry-cordova'; - - Sentry.init({ dsn: '___PUBLIC_DSN___' }); - -In order to also use the Ionic provided ``IonicErrorHandler`` we need to add -``SentryIonicErrorHandler``: - -.. code-block:: javascript - - import { IonicErrorHandler } from 'ionic-angular'; - - import * as Sentry from 'sentry-cordova'; - - class SentryIonicErrorHandler extends IonicErrorHandler { - handleError(error) { - super.handleError(error); - try { - Sentry.captureException(error.originalError || error); - } catch (e) { - console.error(e); - } - } - } - - -Then change the ``@NgModule{providers:[]}`` in ``app.module.ts`` to: - -.. code-block:: javascript - - @NgModule({ - ... - providers: [ - StatusBar, - SplashScreen, - // {provide: ErrorHandler, useClass: IonicErrorHandler} remove this, add next line - {provide: ErrorHandler, useClass: SentryIonicErrorHandler} - ] - }) diff --git a/docs/sentry-doc-config.json b/docs/sentry-doc-config.json deleted file mode 100644 index 6b05dcb..0000000 --- a/docs/sentry-doc-config.json +++ /dev/null @@ -1,14 +0,0 @@ -{ - "support_level": "production", - "platforms": { - "cordova": { - "name": "Cordova", - "type": "language", - "doc_link": "", - "wizard": [ - "index#installation", - "index#configuration" - ] - } - } - } \ No newline at end of file