Skip to content

New way of marking product feature related code snippet sections #12955

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Closed
adinauer opened this issue Mar 7, 2025 · 2 comments · Fixed by #13361
Closed

New way of marking product feature related code snippet sections #12955

adinauer opened this issue Mar 7, 2025 · 2 comments · Fixed by #13361
Assignees
@a-hariti
Labels
getsentry/sentry-docs Type: Platform

Comments

@adinauer
Copy link
Member

adinauer commented Mar 7, 2025

Problem Statement

We currently use line number ranges to mark areas in code snippets that can be toggled (visible/invisible) based on product features being enabled/disabled.

This is brittle and has caused multiple SDKs to have broken docs already.
It is easy to forget updating the line number range and also easy miss in a code review.

Updating the number range requires copying the snippet into an editor and using that for line numbers. You then also have to guess whether it's 0 or 1 based.

Example:

yaml {filename:application.yml} {"onboardingOptions": {"performance": "7-11"}}
...

Solution Brainstorm

Maybe we can instead use some sort of marker (comment) in code snippets that automatically moves when code snippets are updated.

e.g.

sentry:
  dsn: ___PUBLIC_DSN___

  # Add data like request headers and IP for users,
  # see https://docs.sentry.io/platforms/java/guides/spring-boot/data-management/data-collected/ for more info
  send-default-pii: true

___onboardingOptionsStartMarker: performance___
  # Set traces_sample_rate to 1.0 to capture 100%
  # of transactions for tracing.
  # We recommend adjusting this value in production.
  tracesSampleRate: 1.0
___onboardingOptionsEndMarker: performance___
@github-project-automation github-project-automation bot moved this to Backlog in Docs Platform Mar 7, 2025
@a-hariti a-hariti self-assigned this Apr 4, 2025
@a-hariti
Copy link
Collaborator

I have a working prototype with this syntax

  // ___product_option_start___ performance
  // some lines here
  // ___product_option_end___ performance

the markers are not rendered,
and solution does not care about the comment syntax difference between languages (as long as it has the ___ sentinel strings)

do you think we should support both syntaxes for the migration or switch to the new syntax and bring everyone to the PR before the merge?

@adinauer @chargome

@a-hariti a-hariti mentioned this issue Apr 11, 2025
Merged
@adinauer
Copy link
Member Author

do you think we should support both syntaxes for the migration or switch to the new syntax and bring everyone to the PR before the merge?

I don't mind either way, I just think the old way of doing this is very easy to break so we should replace it rather sooner than later. But I guess we can also ask SDK engineers to take a look at their SDK docs and update.

@github-project-automation github-project-automation bot moved this from Backlog to Done in Docs Platform Apr 16, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@a-hariti a-hariti

Labels
getsentry/sentry-docs Type: Platform
Projects
Docs Platform
Status: Done
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

feat: Inline onboarding product options syntax getsentry/sentry-docs
3 participants
@adinauer @stephanie-anderson @a-hariti