docs: update some docs (#208)

* docs: update some docs * refactor(report): extract function * docs: upgrade to docusaurus v3 * docs: remove deprecated flipper docs * docs: add pricing page * docs: add install command in most pages * docs: point to BAM's article * chore: fix eslint warning
bamlab · Mar 12, 2024 · 5cea89c · 5cea89c
1 parent 9c453c2
commit 5cea89c
Show file tree

Hide file tree

Showing 16 changed files with 4,035 additions and 3,552 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -94,15 +94,6 @@ You should now be able to open [the local server](http://localhost:1234/)
 
 Run `yarn jest Plugin -u` after modifications.
 
-### Flipper plugin
+### Running the docs website locally
 
-- Add the path to the `packages` folder in `~/.flipper/config.json`.
-
-For instance, my `config.json` is currently
-`{"pluginPaths":["/Users/almouro/dev/projects/android-performance-profiler/packages"],"disabledPlugins":[],"darkMode":"system","updaterEnabled":true,"launcherEnabled":true,"lastWindowPosition":{"x":-195,"y":-1415,"width":1280,"height":1415}}`
-
-- in the `packages/flipper-plugin-android-performance-profiler`, run `yarn watch`.
-
-You should now see your local plugin in Flipper (ensure you have uninstalled the one from the marketplace), in the disabled plugin section if you're installing for the first time.
-
-⚠️ _when modifying files outside of the `packages/flipper-plugin-android-performance-profiler`, live reload sometimes doesn't work and you need to re-run `yarn watch` for changes to take effect_ 😕
+[See details here](./website/README.md)
diff --git a/packages/commands/report/writeReport.ts b/packages/commands/report/writeReport.ts
@@ -47,6 +47,27 @@ const copyVideoFiles = (results: TestCaseResult[], outputDir: string) => {
   });
 };
 
+export const getResultsFromPaths = (jsonPaths: string[]): TestCaseResult[] => {
+  const getJsonPaths = () => {
+    return jsonPaths
+      .map((path) => {
+        const isDirectory = fs.lstatSync(path).isDirectory();
+
+        if (isDirectory) {
+          return fs
+            .readdirSync(path)
+            .filter((file) => file.endsWith(".json"))
+            .map((file) => `${path}/${file}`);
+        } else {
+          return path;
+        }
+      })
+      .flat();
+  };
+
+  return getJsonPaths().map((path) => JSON.parse(fs.readFileSync(path, "utf8")));
+};
+
 export const writeReport = ({
   jsonPaths,
   outputDir,
@@ -68,27 +89,7 @@ export const writeReport = ({
     .replace(`src="${scriptName}"`, `src="${newJsFile}"`)
     .replace('type="module"', "");
 
-  const getJsonPaths = () => {
-    return jsonPaths
-      .map((path) => {
-        const isDirectory = fs.lstatSync(path).isDirectory();
-
-        if (isDirectory) {
-          return fs
-            .readdirSync(path)
-            .filter((file) => file.endsWith(".json"))
-            .map((file) => `${path}/${file}`);
-        } else {
-          return path;
-        }
-      })
-      .flat();
-  };
-
-  const results: TestCaseResult[] = getJsonPaths().map((path) =>
-    JSON.parse(fs.readFileSync(path, "utf8"))
-  );
-
+  const results = getResultsFromPaths(jsonPaths);
   const isIOSTestCaseResult = results.every((result) => result.type === "IOS_EXPERIMENTAL");
 
   const report = JSON.stringify(getMeasuresForTimeInterval({ results, skip, duration }));

diff --git a/packages/core/web-reporter-ui/src/sections/threads.tsx b/packages/core/web-reporter-ui/src/sections/threads.tsx
@@ -1,4 +1,3 @@
-import React from "react";
 import { AveragedTestCaseResult, TestCaseResult, ThreadNames } from "@perf-profiler/types";
 import { RNLogo } from "../components/icons/ReactNativeLogo";
 import { FlutterLogo } from "../components/icons/FlutterLogo";

diff --git a/website/docs/cloud/cli.md b/website/docs/cloud/cli.md
@@ -6,6 +6,8 @@ sidebar_position: 2
 
 [flashlight.dev](https://flashlight.dev) is now in open beta! 🥳
 
+<Install />
+
 ## Usage
 
 Create your API key [here](https://app.flashlight.dev/api-key) and set it as an environment variable:

diff --git a/website/docs/cloud/pricing.md b/website/docs/cloud/pricing.md
@@ -0,0 +1,11 @@
+# Pricing
+
+`flashlight cloud` and [flashlight.dev](https://app.flashlight.dev) are running with BAM's servers and AWS Device Farm account.
+
+We offer those services **completely free** 🥳  
+However, this means there can be a queue while waiting for devices to be available. (BAM's projects and clients also have priority.)
+
+### Going further
+
+If you'd like to go further, like integrate with your own CI or device farm, contact us:
+<Contact />
diff --git a/website/docs/flipper.md b/website/docs/flipper.md
diff --git a/website/docs/guides/react-native/example-list-performance.md b/website/docs/guides/react-native/example-list-performance.md
@@ -0,0 +1,5 @@
+# Example: Measuring list scrolling performance
+
+![flashlight report](https://assets-global.website-files.com/62c6fbddb12bb54622241c3d/651705b69d012ff086713b43_flashlight%20report.png)
+
+Check out [this article](https://www.bam.tech/article/measuring-react-native-performance-with-flashlight) going in details on how to use the different `flashlight` commands to compare performance between `FlatList` and [`FlashList`](https://shopify.github.io/flash-list/)
diff --git a/website/docs/index.md b/website/docs/index.md
@@ -4,26 +4,7 @@ sidebar_position: 1
 
 # Getting started
 
-## Installation
-
-Install the CLI with:
-
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-import CodeBlock from '@theme/CodeBlock';
-
-<Tabs>
-  <TabItem value="unix" label="macOS/Linux" default>
-    <CodeBlock language="bash">
-      curl https://get.flashlight.dev | bash
-    </CodeBlock>
-  </TabItem>
-  <TabItem value="windows" label="Windows">
-    <CodeBlock language="bash">
-      iwr https://get.flashlight.dev/windows -useb | iex
-    </CodeBlock>
-  </TabItem>
-</Tabs>
+<Install />
 
 ## Simple usage
 

diff --git a/website/docs/test/api.md b/website/docs/test/api.md
@@ -5,27 +5,27 @@
 Run a test several times and measure performance.
 
 Main usage:
-flashlight test --bundleId <your app id\> --testCommand <your test command\>
+flashlight test --bundleId \<your app id\> --testCommand \<your test command\>
 
 Example with Maestro:
 flashlight test --bundleId com.example.app --testCommand "maestro test flow.yml"
 
 ## Options
 
-| Option                                   | Description                                                                                                                                   |
-| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
-| --testCommand <testCommand\>             | Test command (e.g. `maestro test flow.yml`). App performance during execution of this script will be measured over several iterations.        |
-| --bundleId <bundleId\>                   | Bundle id of your app                                                                                                                         |
-| --iterationCount <iterationCount\>       | Amount of iterations to be run. Results will be averaged. (default: 10)                                                                       |
-| --maxRetries <maxRetries\>               | Maximum number of retries allowed over all iterations. (default: 3)                                                                           |
-| --duration <duration\>                   | Duration (in ms) is optional, but helps in getting consistent measures. Measures will be taken for this duration, regardless of test duration |
-| --beforeEachCommand <beforeEachCommand\> | Command to be run before each test iteration                                                                                                  |
-| --afterEachCommand <afterEachCommand\>   | Command to be run after each test iteration                                                                                                   |
-| --beforeAllCommand <beforeAllCommand\>   | Command to be run before all test iterations                                                                                                  |
-| --resultsFilePath <resultsFilePath\>     | Path where the JSON of results will be written                                                                                                |
-| --resultsTitle <resultsTitle\>           | Result title that is displayed at the top of the report                                                                                       |
-| --record                                 | Allows you to record a video of the test. This is useful for debugging purposes.                                                              |
-| --recordBitRate <recordBitRate\>         | Value may be specified as bits or megabits, e.g. '4000000' is equivalent to '4M'.                                                             |
-| --recordSize <recordSize\>               | For best results, use a size supported by the AVC encoder.                                                                                    |
-| --logLevel <logLevel\>                   | Set Log level (choices: "error", "warn", "success", "info", "debug", "trace")                                                                 |
-| -h, --help                               | display help for command                                                                                                                      |
+| Option                                    | Description                                                                                                                                   |
+| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| --testCommand \<testCommand\>             | Test command (e.g. `maestro test flow.yml`). App performance during execution of this script will be measured over several iterations.        |
+| --bundleId \<bundleId\>                   | Bundle id of your app                                                                                                                         |
+| --iterationCount \<iterationCount\>       | Amount of iterations to be run. Results will be averaged. (default: 10)                                                                       |
+| --maxRetries \<maxRetries\>               | Maximum number of retries allowed over all iterations. (default: 3)                                                                           |
+| --duration \<duration\>                   | Duration (in ms) is optional, but helps in getting consistent measures. Measures will be taken for this duration, regardless of test duration |
+| --beforeEachCommand \<beforeEachCommand\> | Command to be run before each test iteration                                                                                                  |
+| --afterEachCommand \<afterEachCommand\>   | Command to be run after each test iteration                                                                                                   |
+| --beforeAllCommand \<beforeAllCommand\>   | Command to be run before all test iterations                                                                                                  |
+| --resultsFilePath \<resultsFilePath\>     | Path where the JSON of results will be written                                                                                                |
+| --resultsTitle \<resultsTitle\>           | Result title that is displayed at the top of the report                                                                                       |
+| --record                                  | Allows you to record a video of the test. This is useful for debugging purposes.                                                              |
+| --recordBitRate \<recordBitRate\>         | Value may be specified as bits or megabits, e.g. '4000000' is equivalent to '4M'.                                                             |
+| --recordSize \<recordSize\>               | For best results, use a size supported by the AVC encoder.                                                                                    |
+| --logLevel \<logLevel\>                   | Set Log level (choices: "error", "warn", "success", "info", "debug", "trace")                                                                 |
+| -h, --help                                | display help for command                                                                                                                      |
diff --git a/website/docs/test/getting-started.md b/website/docs/test/getting-started.md
@@ -4,6 +4,8 @@ sidebar_position: 1
 
 # Getting started
 
+<Install />
+
 ## 1. Run the test command
 
 If you have an e2e test script, you can run:
@@ -16,8 +18,8 @@ flashlight test --bundleId <your app bundle id> \
 ```
 
 - This will run your e2e test 10 times (by default), measure performance during 10s for each iteration and write measures to `results.json`
-- Use `npx @perf-profiler/profiler getCurrentApp` to display the bundle id of the app opened on your phone
-- _⚠️ Your e2e test command should start the app_
+- Use `flashlight tools android_get_bundle_id` to display the bundle id of the app opened on your phone
+- _⚠️ If your e2e test doesn't start the app, add `--skipRestart` to the `flashlight test` command_
 
 ### Example: quickly measure startup performance
 
@@ -40,6 +42,8 @@ To go further, use a proper e2e testing framework (Appium, Detox, Maestro...).
 If you're not using one yet, we recommend to use [Maestro](https://github.com/mobile-dev-inc/maestro)!
 Check out our [Maestro guide](./maestro) to get started quickly with Flashlight and Maestro.
 
+You can also check the full command options [here](./api)
+
 ## 2. Open the web report
 
 You can then open the web report for those measures:

diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js
@@ -1,6 +1,9 @@
 // @ts-check
 // Note: type annotations allow type checking and IDEs autocompletion
 
+/* eslint-disable import/no-unresolved */
+import { themes } from "prism-react-renderer";
+
 /** @type {import('@docusaurus/types').Config} */
 const config = {
   title: "Flashlight",
@@ -93,7 +96,7 @@ const config = {
       },
 
       prism: {
-        darkTheme: require("prism-react-renderer/themes/vsDark"),
+        darkTheme: themes.vsDark,
       },
 
       // forceDarkMode: true,

diff --git a/website/package.json b/website/package.json
@@ -15,19 +15,19 @@
     "typecheck": "tsc"
   },
   "dependencies": {
-    "@docusaurus/core": "2.3.0",
-    "@docusaurus/preset-classic": "2.3.0",
-    "@docusaurus/theme-search-algolia": "^2.3.1",
-    "@mdx-js/react": "^1.6.22",
-    "clsx": "^1.2.1",
-    "prism-react-renderer": "^1.3.5",
-    "react": "^17.0.2",
-    "react-dom": "^17.0.2"
+    "@docusaurus/core": "^3.1.1",
+    "@docusaurus/preset-classic": "^3.1.1",
+    "@docusaurus/theme-search-algolia": "^3.1.1",
+    "@mdx-js/react": "^3.0.1",
+    "clsx": "^2.1.0",
+    "prism-react-renderer": "^2.3.1",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "2.3.0",
-    "@tsconfig/docusaurus": "^1.0.5",
-    "typescript": "^4.7.4"
+    "@docusaurus/module-type-aliases": "3.1.1",
+    "@tsconfig/docusaurus": "^2.0.2",
+    "typescript": "^5.4.2"
   },
   "browserslist": {
     "production": [

diff --git a/website/src/components/Contact.mdx b/website/src/components/Contact.mdx
@@ -1,4 +1,4 @@
-Feel free to reach out ☺️:
+Feel free to reach out:
 
 - request help on [Slack](https://join.slack.com/t/flashlightgroupe/shared_invite/zt-1tscnlvth-rIutTnr5DksxxdGcqoY_cw) in the #help channel
 - submit a [Github issue](https://github.com/bamlab/flashlight/issues)

diff --git a/website/src/components/Install.mdx b/website/src/components/Install.mdx
@@ -0,0 +1,16 @@
+## Installation
+
+Install the CLI with:
+
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+import CodeBlock from "@theme/CodeBlock";
+
+<Tabs>
+  <TabItem value="unix" label="macOS/Linux" default>
+    <CodeBlock language="bash">curl https://get.flashlight.dev | bash</CodeBlock>
+  </TabItem>
+  <TabItem value="windows" label="Windows">
+    <CodeBlock language="bash">iwr https://get.flashlight.dev/windows -useb | iex</CodeBlock>
+  </TabItem>
+</Tabs>
diff --git a/website/src/theme/MDXComponents.js b/website/src/theme/MDXComponents.js
@@ -1,14 +1,12 @@
 /* eslint-disable import/no-unresolved */
-// Import the original mapper
 import MDXComponents from "@theme-original/MDXComponents";
 import Contact from "@site/src/components/Contact.mdx";
+import Install from "@site/src/components/Install.mdx";
 
 const _module = {
-  // Re-use the default mapping
   ...MDXComponents,
-  // Map the "<Highlight>" tag to our Highlight component
-  // `Highlight` will receive all props that were passed to `<Highlight>` in MDX
   Contact,
+  Install,
 };
 
 export default _module;