feat: Adding new docs for sentry-cocoa 5.x

__tests__/__snapshots__/documentation.js.snap

@@ -298,6 +298,9 @@ Array [
   "performance/performance-glossary/index.html",
   "platforms/android/index.html",
   "platforms/android/migrate/index.html",
+  "platforms/cocoa/dsym/index.html",
+  "platforms/cocoa/index.html",
+  "platforms/cocoa/usage/index.html",
   "platforms/dotnet/aspnetcore/index.html",
   "platforms/dotnet/entityframework/index.html",
   "platforms/dotnet/index.html",

src/_data/platforms.yml

@@ -311,13 +311,10 @@
       support_level: production
       type: language
       name: Swift
-      doc_link: /clients/cocoa/
+      doc_link: /platforms/cocoa/
       wizard_parent: cocoa
       wizard:
-        - _documentation/clients/cocoa/index.md
-        - _documentation/clients/cocoa/dsym.md
-      version: 4.1.0
-      version_key: SENTRY_COCOA_TAG
+        - _documentation/platforms/cocoa/index.md
 -
       slug: browser
       support_level: production
@@ -454,13 +451,10 @@
       support_level: production
       type: language
       name: Objective-C
-      doc_link: /clients/cocoa/
+      doc_link: /platforms/cocoa/
       wizard_parent: cocoa
-      wizard:
-        - _documentation/clients/cocoa/index.md
-        - _documentation/clients/cocoa/dsym.md
-      version: 4.1.0
-      version_key: SENTRY_COCOA_TAG
+      wizard: 
+        - _documentation/platforms/cocoa/index.md
 -
       slug: csharp
       support_level: production

src/collections/_documentation/clients/cocoa/advanced.md

@@ -1,5 +1,6 @@
 ---
 title: 'Advanced Usage'
+robots: noindex
 ---
 
 ## Capturing uncaught exceptions on macOS

src/collections/_documentation/clients/cocoa/dsym.md

@@ -1,5 +1,6 @@
 ---
 title: 'Uploading Debug Symbols'
+robots: noindex
 ---
 
 A dSYM upload is required for Sentry to symoblicate your crash logs for viewing. The symoblication process unscrambles Apple’s crash logs to reveal the function, variables, file names, and line numbers of the crash. The dSYM file can be uploaded through the [sentry-cli](https://github.com/getsentry/sentry-cli) tool or through a [Fastlane](https://fastlane.tools/) action.

src/collections/_documentation/clients/cocoa/index.md

@@ -1,9 +1,9 @@
 ---
 title: Cocoa
-sidebar_relocation: platforms
+robots: noindex
 ---
 
-This is the documentation for our official clients for Cocoa (Swift and Objective-C). Starting with version `3.0.0` we’ve switched our internal code from Swift to Objective-C to maximize compatibility. Also we trimmed the public API of our sdk to a minimum. Some of the lesser used features that were present before are gone now, check out [Migration Guide]({%- link _documentation/clients/cocoa/migration.md -%}#migration) or [Advanced Usage]({%- link _documentation/clients/cocoa/advanced.md -%}#advanced) for details.
+This is the documentation for our official clients for Cocoa (Swift and Objective-C). Starting with version `3.0.0` we’ve switched our internal code from Swift to Objective-C to maximize compatibility. Also we trimmed the public API of our SDK to a minimum. Check out [Migration Guide]({%- link _documentation/clients/cocoa/migration.md -%}#migration) or [Advanced Usage]({%- link _documentation/clients/cocoa/advanced.md -%}#advanced) for details.
 
 ## Getting Started
 Getting started with Sentry is a three step process:

src/collections/_documentation/clients/cocoa/migration.md

@@ -1,5 +1,6 @@
 ---
 title: 'Migration Guide'
+robots: noindex
 ---
 
 ## Upgrade from 2.x.x to 3.x.x {#upgrade-from-2-x-x-to-3-0-x}

src/collections/_documentation/platforms/cocoa/captureMessage/objc.md

@@ -0,0 +1,3 @@
+```objc
+[SentrySDK captureMessage:@"My first test message"];
+```

src/collections/_documentation/platforms/cocoa/captureMessage/swift.md

@@ -0,0 +1,3 @@
+```swift
+SentrySDK.capture(message: "My first test message")
+```

src/collections/_documentation/platforms/cocoa/configureScope/objc.md

@@ -0,0 +1,7 @@
+```objc
+[SentrySDK configureScope:^(SentryScope * _Nonnull scope) {
+    [scope setEnvironment:@"debug"];
+    [scope setTagValue:@"objc" forKey:@"langauge"];
+    [scope setExtraValue:[NSString stringWithFormat:@"%@", self] forKey:@"currentViewController"];
+}];
+```

src/collections/_documentation/platforms/cocoa/configureScope/swift.md

@@ -0,0 +1,7 @@
+```swift
+SentrySDK.configureScope { (scope) in
+    scope.setEnvironment("debug")
+    scope.setTag(value: "swift", key: "language")
+    scope.setExtra(value: String(describing: self), key: "currentViewController")
+}
+```

src/collections/_documentation/platforms/cocoa/crash/objc.md

@@ -0,0 +1,3 @@
+```objc
+[SentrySDK crash];
+```

src/collections/_documentation/platforms/cocoa/crash/swift.md

@@ -0,0 +1,3 @@
+```swift
+SentrySDK.crash()
+```

src/collections/_documentation/platforms/cocoa/dsym.md

@@ -0,0 +1,132 @@
+---
+title: 'Uploading Debug Symbols'
+---
+
+Sentry requires a dSYM upload to symbolicate your crash logs. The symbolication process unscrambles Apple’s crash logs to reveal the function, file names, and line numbers of the crash. Upload the dSYM file using either [sentry-cli](https://github.com/getsentry/sentry-cli) or the [Fastlane](https://fastlane.tools/) action.
+
+## With Bitcode {#dsym-with-bitcode}
+
+If [Bitcode](https://developer.apple.com/library/ios/documentation/IDEs/Conceptual/AppDistributionGuide/AppThinning/AppThinning.html#//apple_ref/doc/uid/TP40012582-CH35-SW2) **is enabled** in your project, you will have to upload the dSYM to Sentry **after** it has finished processing in iTunesConnect. We also recommend using the latest Xcode version for submitting your build. The dSYM can be downloaded either with [Fastlane](#bitcode-fastlane) or with [sentry-cli](#bitcode-sentrycli).
+
+### Using Fastlane {#bitcode-fastlane}
+
+Use the [Fastlane](https://github.com/fastlane/fastlane) action, _download_dsyms_, to download the dSYMs from iTunesConnect and upload to Sentry. The dSYM won’t be generated until **after** the app is done processing on iTunesConnect so this should be run in its own lane.
+
+```ruby
+lane :upload_symbols do
+  download_dsyms # this is the important part
+  upload_symbols_to_sentry(
+    auth_token: 'YOUR_AUTH_TOKEN',
+    org_slug: '___ORG_NAME___',
+    project_slug: '___PROJECT_NAME___',
+  )
+end
+```
+
+{% capture __alert_content -%}
+By default fastlane will connect to sentry.io. For on-prem you need to provide the _api_host_ parameter to instruct the tool to connect to your server:
+
+```
+api_host: 'https://mysentry.invalid/'
+```
+{%- endcapture -%}
+{%- include components/alert.html
+  title="On Prem"
+  content=__alert_content
+%}
+
+### Using `sentry-cli` {#bitcode-sentrycli}
+
+Download the dSYM from iTunesConnect. After that, you can upload the dSYM using [sentry-cli](https://github.com/getsentry/sentry-cli/releases).
+
+1.  Open Xcode Organizer, go to your app, and click “Download dSYMs...”
+2.  Login to iTunes Connect, go to your app, go to “Activity", click the build number to go into the detail page, and click “Download dSYM”
+
+Afterwards manually upload the symbols with _sentry-cli_:
+
+```bash
+sentry-cli --auth-token YOUR_AUTH_TOKEN upload-dif --org ___ORG_NAME___ --project ___PROJECT_NAME___ PATH_TO_DSYMS
+```
+
+{% capture __alert_content -%}
+By default sentry-cli will connect to sentry.io. For on-prem you need to export the _SENTRY_URL_ environment variable to instruct the tool to connect to your server:
+
+```bash
+export SENTRY_URL=https://mysentry.invalid/
+```
+{%- endcapture -%}
+{%- include components/alert.html
+  title="On Prem"
+  content=__alert_content
+%}
+
+## Without Bitcode {#dsym-without-bitcode}
+
+When not using Bitcode you can directly upload the symbols to Sentry as part of your build.
+
+### Using Fastlane
+
+If you are already using Fastlane you can use it in this situation as well:
+
+```ruby
+lane :build do
+  gym # building your app
+  upload_symbols_to_sentry(
+    auth_token: 'YOUR_AUTH_TOKEN',
+    org_slug: '___ORG_NAME___',
+    project_slug: '___PROJECT_NAME___',
+  )
+end
+```
+
+{% capture __alert_content -%}
+By default fastlane will connect to sentry.io. For on-prem you need to provide the _api_host_ parameter to instruct the tool to connect to your server:
+
+```
+api_host: 'https://mysentry.invalid/'
+```
+{%- endcapture -%}
+{%- include components/alert.html
+  title="On Prem"
+  content=__alert_content
+%}
+
+<!-- WIZARD -->
+### Uploading Symbols with _sentry-cli_
+
+Your project’s dSYM can be upload during the build phase as a “Run Script”. For this you need to set the _DEBUG_INFORMATION_FORMAT_ to be _DWARF with dSYM File_. By default, an Xcode project will only have _DEBUG_INFORMATION_FORMAT_ set to _DWARF with dSYM File_ in _Release_ so make sure everything is set in your build settings properly.
+
+You need to have an Auth Token for this to work. You can [create an Auth Token here](https://sentry.io/api/).
+
+1.  Download and install [sentry-cli](https://github.com/getsentry/sentry-cli#installation)
+2.  You will need to copy the script below into a new _Run Script_ and set your _AUTH_TOKEN_, _ORG_SLUG_, and _PROJECT_SLUG_
+```bash
+if which sentry-cli >/dev/null; then
+export SENTRY_ORG=___ORG_NAME___
+export SENTRY_PROJECT=___PROJECT_NAME___
+export SENTRY_AUTH_TOKEN=YOUR_AUTH_TOKEN
+ERROR=$(sentry-cli upload-dif "$DWARF_DSYM_FOLDER_PATH" 2>&1 >/dev/null)
+if [ ! $? -eq 0 ]; then
+echo "warning: sentry-cli - $ERROR"
+fi
+else
+echo "warning: sentry-cli not installed, download from https://github.com/getsentry/sentry-cli/releases"
+fi
+```
+3.  If you are using Xcode 10 or newer, you also need to add the following line to the _Input Files_ section in the _Run Script_ from step 2:
+```bash
+${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}/Contents/Resources/DWARF/${TARGET_NAME}
+```
+
+{% capture __alert_content -%}
+By default sentry-cli will connect to sentry.io. For on-prem you need to export the _SENTRY_URL_ environment variable to instruct the tool to connect to your server:
+
+```bash
+export SENTRY_URL=https://mysentry.invalid/
+```
+{%- endcapture -%}
+{%- include components/alert.html
+  title="On Prem"
+  content=__alert_content
+%}
+<!-- ENDWIZARD -->

src/collections/_documentation/platforms/cocoa/index.md

@@ -0,0 +1,99 @@
+---
+title: Cocoa
+---
+
+{% capture __alert_content -%}
+Version `5.0.0` is in beta.
+{%- endcapture -%}
+{%- include components/alert.html
+  title="Note"
+  content=__alert_content
+  level="info"
+%}
+
+This is the documentation for our Cocoa SDK (Swift and Objective-C).
+If you are migrating from an older version, please consider our [Migration Guide](https://github.com/getsentry/sentry-cocoa/blob/master/MIGRATION.md). Also always make sure to follow the [changelog](https://github.com/getsentry/sentry-cocoa/blob/master/CHANGELOG.md)
+
+<!-- WIZARD -->
+## Installation {#install}
+
+The SDK can be installed using [CocoaPods](http://cocoapods.org), [Carthage](https://github.com/Carthage/Carthage), or [Swift Package Manager](https://swift.org/package-manager/). This is the recommended SDK for both Swift and Objective-C projects.
+
+It supports iOS (>= 8.0), tvOS (>= 9.0), macOS (>= 10.10) and partially watchOS (>= 2.0). 
+
+### CocoaPods
+
+We recommend installing the SDK with CocoaPods..
+To integrate Sentry into your Xcode project, specify it in your _Podfile_:
+
+```ruby
+platform :ios, '8.0'
+use_frameworks! # This is important
+
+target 'YourApp' do
+    pod 'Sentry', :git => 'https://github.com/getsentry/sentry-cocoa.git', :tag => '5.0.0-beta.0'
+end
+```
+<!-- {% sdk_version sentry.cocoa %} -->
+
+Afterwards run `pod install`.
+
+### Carthage
+
+To integrate Sentry into your Xcode project using Carthage, specify it in your _Cartfile_:
+
+```ruby
+github "getsentry/sentry-cocoa" "5.0.0-beta.0"
+```
+
+Run `carthage update` to download the framework and drag the built _Sentry.framework_ into your Xcode project.
+
+We also provide a pre-built version for every release which can be downloaded at [releases on GitHub](https://github.com/getsentry/sentry-cocoa/releases).
+
+### Swift Package Manager
+
+To integrate Sentry into your Xcode project using SPM, open your App in Xcode and open `File` -> `Swift Packages` -> `Add Package Dependency`. Then add the SDK by entering the git repo url `https://github.com/getsentry/sentry-cocoa.git`, and select a version (or branch) on the next page.
+
+NOTE: Version tags or branches need to have the Package.swift file in it or Xcode won't be able to install the package.
+
+## Configuration {#configure}
+
+Make sure you initalize the SDK as soon as possible in your application lifecycle e.g. in your AppDelegate `application:didFinishLaunchingWithOptions` method:
+
+{% include components/platform_content.html content_dir='init' %}
+
+## Debug Symbols {#sentry-cocoa-debug-symbols}
+
+Before capturing crashes, you need to provide debug information to Sentry. Debug information is provided by uploading dSYM files using one of two methods, dependent on your setup:
+
+-   [With Bitcode]({%- link _documentation/platforms/cocoa/dsym.md -%}#dsym-with-bitcode)
+-   [Without Bitcode]({%- link _documentation/platforms/cocoa/dsym.md -%}#dsym-without-bitcode)
+
+<!-- ENDWIZARD -->
+
+## Testing if the SDK works
+
+To validate that the SDK is correctly set up and connected to your Sentry project, capture a test message:
+
+{% include components/platform_content.html content_dir='captureMessage' %}
+
+If everything is working correctly, this message should appear within seconds in your Sentry project.
+
+## Crash Handling
+
+Our SDK hooks into all signal and exception handlers, except for MacOS. If you are using MacOS, please see the additional step provided in [Advanced Usage]({%- link _documentation/platforms/cocoa/usage.md -%})
+To try it out, the SDK provides a test crash function:
+
+{% include components/platform_content.html content_dir='crash' %}
+
+_If you crash with a debugger attached, nothing will happen._
+
+Crashes are submitted only upon re-launch of the application. To view the crash in Sentry, close your app and re-launch it.
+
+
+## Deep Dive
+
+-   [Uploading Debug Symbols]({%- link _documentation/platforms/cocoa/dsym.md -%})
+    -   [With Bitcode]({%- link _documentation/platforms/cocoa/dsym.md -%}#with-bitcode)
+    -   [Without Bitcode]({%- link _documentation/platforms/cocoa/dsym.md -%}#without-bitcode)
+-   [Advanced Usage]({%- link _documentation/platforms/cocoa/usage.md -%})

src/collections/_documentation/platforms/cocoa/init/objc.md

@@ -0,0 +1,11 @@
+```objc
+@import Sentry;
+
+- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
+    [SentrySDK initWithOptions:@{
+        @"dsn": @"___PUBLIC_DSN___",
+        @"debug": @(YES)
+    }];
+    return YES;
+}
+```

src/collections/_documentation/platforms/cocoa/init/swift.md

@@ -0,0 +1,14 @@
+```swift
+import Sentry // Make sure you import Sentry
+
+// ....
+
+func application(_ application: UIApplication, 
+    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
+    _ = SentrySDK(options: [
+        "dsn": "___PUBLIC_DSN___",
+        "debug": true // Enabled debug when first installing is always helpful
+    ])
+    return true
+}
+```

src/collections/_documentation/platforms/cocoa/integrations/objc.md

@@ -0,0 +1,9 @@
+```objc
+NSMutableArray *integrations = [SentryOptions defaultIntegrations].mutableCopy;
+[integrations removeObject:@"SentryUIKitMemoryWarningIntegration"];
+[SentrySDK initWithOptions:@{
+    // ...
+    @"integrations": integrations
+    // ...
+}];
+```

src/collections/_documentation/platforms/cocoa/integrations/swift.md

@@ -0,0 +1,9 @@
+```swift
+_ = SentrySDK(options: [
+    //...
+    "integrations": Sentry.Options.defaultIntegrations().filter { (name) -> Bool in
+        return name != "SentryUIKitMemoryWarningIntegration" // This will disable  SentryUIKitMemoryWarningIntegration
+    }
+    //...
+])
+```