Skip to content
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.

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

feat: replace raw alpha warnings with admonitions when generating C8 REST API docs #4579

Merged
merged 1 commit into from
Nov 7, 2024

Conversation

pepopowitz
Copy link
Collaborator

Description

In camunda/camunda#24340, we removed all docs-specific formatting from the upstream spec. We'd already accounted for adding links in #4541, but we also need to add admonitions for alpha warnings.

This PR turns a text-only alpha warning into a :::note admonition.

This injection has no effect on the current docs spec, because the admonitions are already there -- this is why there are no files changed other than the generation strategy. However, when camunda/camunda#24340 makes it to this project via the weekly spec sync, our spec will be missing admonitions, and we'll want to regenerate with this new step.

When should this change go live?

  • This is a bug fix, security concern, or something that needs urgent release support.
  • This is already available but undocumented and should be released within a week.
  • This on a specific schedule and the assignee will coordinate a release with the DevEx team. (apply hold label or convert to draft PR)
  • This is part of a scheduled alpha or minor. (apply alpha or minor label)
  • There is no urgency with this change and can be released at any time.

PR Checklist

  • My changes are for an already released minor and are in /versioned_docs directory.
  • My changes are for the next minor and are in /docs directory (aka /next/).

@pepopowitz pepopowitz added dx Documentation infrastructure typically handled by the Camunda DX team theme:api-streamline Issues related to the theme of streamlining APIs labels Nov 6, 2024
@pepopowitz pepopowitz requested a review from akeller November 6, 2024 21:14
@pepopowitz pepopowitz self-assigned this Nov 6, 2024
@akeller
Copy link
Member

akeller commented Nov 7, 2024

This injection has no effect on the current docs spec, because the admonitions are already there -- this is why there are no files changed other than the generation strategy. However, when camunda/camunda#24340 makes it to this project via the weekly spec sync, our spec will be missing admonitions, and we'll want to regenerate with this new step.

If I'm understanding this correctly, we cannot test this quite yet. I can give a handwavy approval now, or we can wait until we have something to test. How would you like to proceed @pepopowitz?

@pepopowitz
Copy link
Collaborator Author

Correct. Let's do the hand-wavy thing for now, and I'll kick off a new sync after it merges, to "test in production" real quickly.

@pepopowitz pepopowitz enabled auto-merge (squash) November 7, 2024 16:09
Copy link
Member

@akeller akeller left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👋 👋

@pepopowitz pepopowitz merged commit 45cc388 into main Nov 7, 2024
11 checks passed
@pepopowitz pepopowitz deleted the pepopowitz/c8-generation-improvements-part-2 branch November 7, 2024 17:08
@pepopowitz
Copy link
Collaborator Author

Confirmed in #4581 that this new adjustment works properly.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
dx Documentation infrastructure typically handled by the Camunda DX team theme:api-streamline Issues related to the theme of streamlining APIs
Projects
Archived in project
Development

Successfully merging this pull request may close these issues.

2 participants