docs(contributing): Document new syntax for onboarding snippets (#13469)

* document new product options syntax

* migrate missed line

* remove support for the old options syntax

---------

Co-authored-by: Abdellah Hariti <[email protected]>

Author: 2 people

docs/contributing/pages/components.mdx

@@ -378,20 +378,23 @@ Attributes:
 
 ## Onboarding Options
 
-If you're writing product feature specific docs, you can specify code block `onboardingOptions` metadata:
+If you're writing product feature specific docs, you can specify markers within code blocks that enable or disable certain parts of snippets:
 
 ````markdown
-```go {"onboardingOptions": {"performance": "13-17"}}
-// your code here
+```go
+  // ___PRODUCT_OPTION_START___ performance
+  // your code here
+  // ___PRODUCT_OPTION_END___ performance
 ```
 ````
 
-the general syntax is `{"onboardingOptions": {"feature": "range"}}` where `feature` is the feature id
-and `range` is the corresponding line range (similar to the line highlighting syntax).
+the syntax uses the standard comment style of the programming language you're documenting. For example:
 
-You can specify multiple features by separating them with a comma:
+- TypeScript/JavaScript: `// ___PRODUCT_OPTION_START___ feature`
+- Python: `# ___PRODUCT_OPTION_START___ feature`
+
+where `feature` is the feature id (e.g. `performance`, `profiling` or `session-replay`).
 
-`{"onboardingOptions": {"performance": "13-17", "profiling": "5-6"}}`
 
 The range visibility will be controlled by the `OnboardingOptionButtons` component:
 
@@ -427,7 +430,7 @@ Example (output of the above):
   dontStick
 />
 
-```go {"onboardingOptions": {"performance": "13-17"}}
+```go
 import (
 	"fmt"
 	"net/http"
@@ -440,11 +443,13 @@ import (
 // To initialize Sentry's handler, you need to initialize Sentry itself beforehand
 if err := sentry.Init(sentry.ClientOptions{
 	Dsn: "___PUBLIC_DSN___",
+  // ___PRODUCT_OPTION_START___ performance
 	EnableTracing: true,
 	// Set TracesSampleRate to 1.0 to capture 100%
 	// of transactions for performance monitoring.
 	// We recommend adjusting this value in production,
 	TracesSampleRate: 1.0,
+  // ___PRODUCT_OPTION_END___ performance
   // Adds request headers and IP for users,
   // visit: https://docs.sentry.io/platforms/go/data-management/data-collected/ for more info
   SendDefaultPII: true,

package.json

@@ -74,7 +74,6 @@
     "next-plausible": "^3.12.4",
     "next-themes": "^0.3.0",
     "nextjs-toploader": "^1.6.6",
-    "parse-numeric-range": "^1.3.0",
     "platformicons": "^8.0.1",
     "prism-sentry": "^1.0.2",
     "query-string": "^6.13.1",

platform-includes/debug-symbols-apple/_default.mdx

@@ -31,9 +31,11 @@ You can also upload your code for source context. This feature allows Sentry to
   options={[{ id:"source-context", checked: false }]}
 />
 
-```bash {"onboardingOptions": {"source-context": "2"}}
+```bash
 sentry-cli debug-files upload --auth-token ___ORG_AUTH_TOKEN___ \
+  # ___PRODUCT_OPTION_START___ source-context
   --include-sources \
+  # ___PRODUCT_OPTION_END___ source-context
   --org ___ORG_SLUG___ \
   --project ___PROJECT_SLUG___ \
   PATH_TO_DSYMS

src/rehype-onboarding-lines.js

@@ -3,16 +3,11 @@
  * @typedef {import('hast').Root} Root
  */
 import {toString} from 'hast-util-to-string';
-import rangeParser from 'parse-numeric-range';
 import {visit} from 'unist-util-visit';
 
 /**
- * Rehype plugin that adds the `data-onboarding-option="some-option-id"` attribute and `hidden` class name
- * to each line of code based on the metastring of the code block.
- *
- * The metastring should be in the format of:
- * `{"onboardingOptions": {"performance": "1, 3-4", "profiling": "5-6"}}`
- * where the keys are the onboarding options, the line numbers can be individual or ranges separated by a comma.
+ * a Rehype plugin that adds the `data-onboarding-option="option-id"` attribute and `hidden` class name
+ * to each line of code enclosed within a `___PRODUCT_OPTION_START___ option-id` and `___PRODUCT_OPTION_END___ option-id` markers.
  *
  * These lines will be hidden by default and shown based on the user's selection of `<OnboardingOptionsButtons ... />`
  *
@@ -34,15 +29,6 @@ function visitor(node) {
   if (!node.properties.className?.includes('code-highlight')) {
     return;
   }
-
-  const meta = /** @type {string} */ (
-    node?.data?.meta || node?.properties?.metastring || ''
-  );
-
-  if (meta.includes('onboardingOptions')) {
-    handle_metadata_options(node, meta);
-    return;
-  }
   handle_inline_options(node);
 }
 
@@ -70,74 +56,3 @@ function handle_inline_options(node) {
     }
   });
 }
-
-/**
- * Parse the line numbers from the metastring
- * @param {string} meta
- * @return {number[]}
- * @example
- * parseLines('1, 3-4') // [1, 3, 4]
- * parseLines('') // []
- */
-const parseLines = meta => {
-  const RE = /([\d,-]+)/;
-  // Remove space between {} e.g. {1, 3}
-  const parsedMeta = meta
-    .split(',')
-    .map(str => str.trim())
-    .join(',');
-  if (RE.test(parsedMeta)) {
-    const strlineNumbers = RE.exec(parsedMeta)?.[1];
-    if (!strlineNumbers) {
-      return [];
-    }
-    const lineNumbers = rangeParser(strlineNumbers);
-    return lineNumbers;
-  }
-  return [];
-};
-
-/**
- * Create a closure that returns an onboarding option `id` for a given line if it exists
- *
- * @param {string} meta
- * @return { (index:number) => string | undefined }
- */
-const getOptionForLine = meta => {
-  // match the onboardingOptions object, but avoid `other stuff`
-  const optionsRE = /{"onboardingOptions":\s*({[^}]*})\s*}/;
-  let linesForOptions = {};
-  const options = optionsRE.exec(meta)?.[1];
-  if (!options) {
-    return () => undefined;
-  }
-
-  // eval provides the convenience of not having to wrap the object properties in quotes
-  const parsedOptions = JSON.parse(options);
-  linesForOptions = Object.keys(parsedOptions).reduce((acc, key) => {
-    acc[key] = parseLines(parsedOptions[key]);
-    return acc;
-  }, {});
-  return index => {
-    for (const key in linesForOptions) {
-      if (linesForOptions[key].includes(index + 1)) {
-        return key;
-      }
-    }
-    return undefined;
-  };
-};
-
-/**
- * @param {Element} node
- */
-function handle_metadata_options(node, meta) {
-  const optionForLine = getOptionForLine(meta);
-
-  node.children.forEach((line, index) => {
-    const option = optionForLine(index);
-    if (option) {
-      line.properties['data-onboarding-option'] = option;
-    }
-  });
-}