feat(doc): marathon cloud doc update (#807)

* updated info about Cloud
---------

Co-authored-by: Anton Malinskiy <anton@malinskiy.com>

docs/docs/cloud.md

@@ -5,36 +5,159 @@ title: "Overview"
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
-Marathon Cloud is a cloud testing infrastructure built on top of the Marathon test runner.
+[Marathon Cloud](https://marathonlabs.io/) is a cloud testing infrastructure built on top of the Marathon test runner.
 It automatically provisions virtual devices to accommodate your tests within 15 minutes.
 The test execution is then delegated to Marathon test runner, which handles tasks such as batching, 
 sorting, preventive retries, and post-factum retries. 
 This ensures an even distribution of tests across the provisioned devices. 
 
+## Install
 
-## What you'll need
+The installation can be performed using [Homebrew](https://brew.sh/):
+```shell
+brew install malinskiy/tap/marathon-cloud
+```
+Alternatively, you can download prebuilt binaries for Windows, Linux, or MacOS from [the Release page](https://github.com/MarathonLabs/marathon-cloud-cli/releases).
 
-To utilize Marathon Cloud, please ensure you have the following:
-- Marathon Cloud account ([Sign up or Sign here](https://cloud.marathonlabs.io/signup))
-- API Key: You can create an API Key by following the [link](https://cloud.marathonlabs.io/tokens) provided.
-- CLI or CI/CD plugin: Make sure you have the [Command Line Interface (CLI)](https://github.com/MarathonLabs/marathon-cloud-cli) or the appropriate Continuous Integration/Continuous Deployment (CI/CD) plugin installed.
-- Application with tests for iOS or Android
+## API Key
 
-## Application requirements
+Token creation and management are available at [the Tokens page](https://cloud.marathonlabs.io/tokens). Generate a token and save it somewhere safe for the next step.
+
+## Prepare bundles for testing
 
 ### iOS
 
-Marathon Cloud supports tests written with XCTest and XCUITest frameworks.
-Both the application and the tests must be built for the ARM architecture.
-When dealing with iOS applications and tests, please compress them into ZIP archives.
-For instance, if your project is named "SampleApp," navigate to Product -> Show Build Folder in Finder. 
-In the opened Finder window, you'll find the required folders/applications for testing: "SampleApp.app" for the application and "SampleAPPUITests-Runner.app" for the Testing Application.
+Marathon Cloud supports tests written with **XCTest and XCUITest frameworks**.
+Both the application and the tests must be built for the **ARM architecture**.
+
+Before initiating the testing process for your iOS application, you’ll need to create two `.app` bundles: one for the application that's being tested (`.ipa` format for application is supported too), and another for the tests themselves. Typically, `debug` variants are utilized for this purpose.
+
+Let's say our project is called "Sample". The code snippet below shows how to build the .app bundle:
+
+```shell
+# file structure
+# |
+# |--home
+#    |--john
+#       |--sample <== you are here
+#          |--sample  <== it's your application
+#          ...
+#          |--sample.xcodeproj
+
+xcodebuild build-for-testing \
+  -project sample.xcodeproj \
+  -scheme sample \
+  -destination 'platform=iOS Simulator,name=iPhone 14,OS=16.1' \
+  -derivedDataPath ./build
+```
+
+Note the relative paths of applications, as they will be required for running the tests. In the context of our example and `debug` build, these files can be located at the following paths:
+
+- Application: `/home/john/sample/build/Build/Products/Debug-iphonesimulator/sample.app`
+- Test APK: `/home/john/sample/build/Build/Products/Debug-iphonesimulator/sampleUITests-Runner.app`
+
+One important thing to note is that `*.app` files are actually folders in disguise. To transfer them, it's necessary to convert these bundles into standard zip archives:
+
+```shell
+# file structure
+# |
+# |--home
+#    |--john
+#       |--sample <== you are here
+#          |--build  <== derivedData folder
+#          |--sample <== it's your application
+#          ...
+#          |--sample.xcodeproj
+cd build/Build/Products/Debug-iphonesimulator
+zip -r sample.zip sample.app
+zip -r sampleUITests-Runner.zip sampleUITests-runner.app 
+```
+
+Further, we will use these files:
+
+- Application: `/home/john/sample/build/Build/Products/Debug-iphonesimulator/sample.zip`
+- Test APK: `/home/john/sample/build/Build/Products/Debug-iphonesimulator/sampleUITests-Runner.zip`
 
 ### Android
 
-Marathon Cloud supports tests written with UIAutomator, Cucumber, Espresso, and Kaspresso frameworks.
-You will need APK files for both the application and the tests.
+Marathon Cloud supports tests written with **UIAutomator, Cucumber, Espresso, and [Kaspresso](https://github.com/KasperskyLab/Kaspresso) frameworks**.
+
+Before initiating the testing process for your application, you’ll require two APK files: one for the application that’s being tested, and another for the tests themselves. Typically, `debug` variants are utilized for this purpose.
+
+If the primary application resides under the `app/` subproject, you can execute the following command to build both the app and test APK:
+
+```shell
+# file structure
+# |
+# |--home
+#    |--john
+#       |--project <== you are here
+#          |--app  <== it's your primary application
+#          ...
+#          |--build.gragle
+#          |--settings.gradle  
+./gradlew :app:assembleDebug :app:assembleDebugAndroidTest
+```
+
+Be sure to note the relative paths of the test APK and the app APK, as they will be required for running the tests. In the context of our example, involving the `app` project and the `debug` build, these files can be located at the following paths:
+
+- App APK: `/home/john/project/app/build/outputs/apk/debug/app-debug.apk`
+- Test APK: `/home/john/project/app/build/outputs/apk/androidTest/debug/app-debug-androidTest.apk`
+
+
+## Samples (optional)
+
+To showcase the advantages of Marathon Cloud compared to other solutions, we've prepared a sample app with 300 tests, of which 15% are flaky. During the initial run, our platform will gather information about the tests. During the second run, it will optimize it to fit within 15 minutes.
+<Tabs>
+<TabItem value="iOS" label="iOS">
+
+```shell
+# Download the prebuilt iOS Application
+curl https://cloud.marathonlabs.io/samples/ios/sample.zip -o sample.zip
+
+# Download the prebuilt iOS Test Application
+curl https://cloud.marathonlabs.io/samples/ios/sampleUITests-Runner.zip -o sampleUITests-Runner.zip
+```
+
+</TabItem>	
+<TabItem value="Android" label="Android">
+
+```shell
+# Download the prebuilt Android Application
+curl https://cloud.marathonlabs.io/samples/android/app.apk -o app.apk
+
+# Download the prebuilt Android Test Application
+curl https://cloud.marathonlabs.io/samples/android/appTest.apk -o appTest.apk
+```
+
+</TabItem>
+</Tabs>
+
+## Execution
+
+Now you can start running your tests. Use the following command to execute the CLI with the necessary parameters:
+
+<Tabs>
+<TabItem value="iOS" label="iOS">
+
+```shell
+marathon-cloud \
+	-api_key api_key \
+	-apk sample.zip \
+	-testapk sampleUITests-Runner.zip
+```
+
+</TabItem>	
+<TabItem value="Android" label="Android">
+
+```shell
+marathon-cloud \
+	-api_key api_key \
+	-apk app.apk \
+	-testapk appTest.apk
+```
 
-## Installation
+</TabItem>
+</Tabs>
 
-Please look at CLI [Readme on Github](https://github.com/MarathonLabs/marathon-cloud-cli).
+For additional parameters, refer to the [marathon-cloud-cli README](https://github.com/MarathonLabs/marathon-cloud-cli/#installation).

docs/yarn.lock

@@ -8353,4 +8353,4 @@ yocto-queue@^0.1.0:
 zwitch@^1.0.0:
   version "1.0.5"
   resolved "https://registry.npmjs.org/zwitch/-/zwitch-1.0.5.tgz"
-  integrity sha512-V50KMwwzqJV0NpZIZFwfOD5/lyny3WlSzRiXgA0G7VUnRlqttta1L6UQIHzd6EuBY/cHGfwTIck7w1yH6Q5zUw==
+  integrity sha512-V50KMwwzqJV0NpZIZFwfOD5/lyny3WlSzRiXgA0G7VUnRlqttta1L6UQIHzd6EuBY/cHGfwTIck7w1yH6Q5zUw==