Skip to content

Conversation

Mpdreamz
Copy link
Member

@Mpdreamz Mpdreamz commented Mar 28, 2025

This PR adds support for Myst inline role syntax.

These take the following syntax:

Some paragraph containing {role}`content`. 

The `content` component is required.

The first role we support is {applies_to} and `{preview}``

image

This revisits an earlier discussion (#94) where we opted to not implement this but recent examples in the wild highlighted that we need to build this.

Otherwise the only remedy for writers/dev's is to include non uniform admonitions calling these out.

This PR adds support for Myst inline role syntax.

The first `role` we support is `{applies_to}` and `{preview}``
@Mpdreamz Mpdreamz requested a review from a team as a code owner March 28, 2025 22:39
@Mpdreamz Mpdreamz self-assigned this Mar 28, 2025
@Mpdreamz
Copy link
Member Author

Myst documents

{role}`arguments`

Sphinx documents

:role:`arguments`

The latter will stand out more if we ever support argument-less roles e.g

This is paragraph with an inline :role:

Although we might want to use : delimited keywords for emoticons/icons too.

@leemthompo
Copy link
Contributor

it takes a required version argument

In my experience, in 99% of cases a feature's lifecycle is identical across deployment types, e.g. very rarely is something tech preview on ECH but not tech preview on serverless. So maybe we'd want the version to be an optional argument.

Regarding future stack version availability, the pattern is basically that everything gets released in serverless first. I'd think we might want to lean into saying something like "Serverless only" (in full prose: "This feature is currently only available on Serverless"), instead of indicating a planned version number for availability in the stack, which also raises legal concerns.

I'd also ++ @shainaraskas's idea to beef up these pills/tags with more information via tooltips or something equivalent. I think currently the pills aren't visible enough, informative enough, or color-coded intuitively enough. This would also help solve the DIY admonitions we have all over the place.

@jmikell821
Copy link
Contributor

Hello! Adding a few examples so we can consider these scenarios when formalizing guidelines. In Security, we often have granular changes (such as a new setting or privilege) that are merged into serverless first, then typically get rolled into the stack release.

Here's an example where the UI is slightly different between serverless and the stack.

2025-04-01_12-01-09
2025-04-01_12-00-42

Also, in this Endpoint response actions doc, you can see notated differences between serverless and stack privileges.

2025-04-01_22-18-04

@Mpdreamz
Copy link
Member Author

Mpdreamz commented Apr 2, 2025

Discussed with @KOTungseth

Merging this in without restrictions but the guidelines for them will be to limit their usage to reference content and only as badges for configuration items.

We can look into enforcing this restriction later.

@Mpdreamz Mpdreamz merged commit 97ede38 into main Apr 2, 2025
14 checks passed
@Mpdreamz Mpdreamz deleted the feature/myst-roles-inline-applies branch April 2, 2025 15:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants