[docs] display beta warning and decorator info (#26821)

## Summary & Motivation

Same as #25362 but for the new
beta decorator introduced in
#26748

docs/content/about/releases.mdx

@@ -29,6 +29,12 @@ The "preview" marker allows us to offer APIs in early testing phase to users and
 
 Preview APIs may change or disappear within any release and are not considered ready for production use.
 
+### Beta APIs
+
+The "beta" marker allows us to offer APIs in development and testing phase to users and rapidly iterate based on their feedback. Beta APIs are marked as such in the [API reference](/\_apidocs) and usually raise a <PyObject object="BetaWarning" module="dagster._utils.warnings" /> when used.
+
+Beta APIs may have breaking changes in minor version releases, with behavior changes in patch releases, but we try to avoid breaking them within minor releases if they have been around for a long time.
+
 ### Superseded APIs
 
 The "superseded" marker indicates that we recommend avoiding an API, usually because there's a preferred option that should be used instead.

docs/markdoc-component-documentation.md

@@ -281,6 +281,7 @@ There are the available badges:
 
 - `{% experimental /%}` {% experimental /%}
 - `{% preview /%}` {% preview /%}
+- `{% beta /%}` {% beta /%}
 - `{% deprecated /%}` {% deprecated /%}
 - `{% superseded /%}` {% superseded /%}
 - `{% legacy /%}` {% legacy /%}

docs/next/components/markdoc/Badges.tsx

@@ -27,6 +27,14 @@ export const Preview = () => {
   );
 };
 
+export const Beta = () => {
+  return (
+    <div className="beta-tag">
+      <span className="hidden">(</span>Beta<span className="hidden">)</span>
+    </div>
+  );
+};
+
 export const Deprecated = () => {
   return (
     <div className="deprecated-tag">

docs/next/components/mdx/MDXComponents.tsx

@@ -441,6 +441,18 @@ const Preview = () => {
   );
 };
 
+////////////////////////
+//  Beta BADGE  //
+////////////////////////
+
+const Beta = () => {
+  return (
+      <div className="beta-tag">
+        <span className="hidden">(</span>Beta<span className="hidden">)</span>
+      </div>
+  );
+};
+
 ////////////////////////
 //  DEPRECATED BADGE  //
 ////////////////////////
@@ -879,6 +891,7 @@ export default {
   Deprecated,
   Superseded,
   Preview,
+  Beta,
   Legacy,
   Icons,
   ReferenceTable,

docs/next/markdoc/tags.js

@@ -1,5 +1,5 @@
 import {ArticleList, ArticleListItem} from '../components/markdoc/ArticleList';
-import {Badge, Experimental, Preview, Deprecated, Superseded, Legacy} from '../components/markdoc/Badges';
+import {Badge, Experimental, Preview, Beta, Deprecated, Superseded, Legacy} from '../components/markdoc/Badges';
 import {Button, ButtonContainer} from '../components/markdoc/Button';
 import {Note, Warning} from '../components/markdoc/Callouts';
 import {Check, Cross} from '../components/markdoc/CheckCross';
@@ -85,6 +85,11 @@ export const preview = {
   selfClosing: true,
 };
 
+export const beta = {
+  render: Beta,
+  selfClosing: true,
+};
+
 export const deprecated = {
   render: Deprecated,
   selfClosing: true,

docs/next/styles/globals.css

@@ -109,6 +109,11 @@ dt > a.reference.internal {
   @apply inline-flex items-center px-3 py-0.5 rounded-full align-middle text-xs uppercase font-medium bg-sea-foam text-gable-green
 }
 
+.beta-tag,
+.flag.beta {
+  @apply inline-flex items-center px-3 py-0.5 rounded-full align-middle text-xs uppercase font-medium bg-sea-foam text-gable-green
+}
+
 .deprecated-tag {
   @apply inline-flex items-center px-3 py-0.5 rounded-full align-middle text-xs uppercase font-medium bg-gray-300 text-gray-900
 }

docs/sphinx/_ext/dagster-sphinx/dagster_sphinx/__init__.py

@@ -2,6 +2,7 @@
 
 import docutils.nodes as nodes
 from dagster._annotations import (
+    get_beta_info,
     get_deprecated_info,
     get_deprecated_params,
     get_experimental_info,
@@ -10,6 +11,7 @@
     get_superseded_info,
     has_deprecated_params,
     has_experimental_params,
+    is_beta,
     is_deprecated,
     is_experimental,
     is_preview,
@@ -131,6 +133,9 @@ def process_docstring(
     if is_preview(obj):
         inject_object_flag(obj, get_preview_info(obj), lines)
 
+    if is_beta(obj):
+        inject_object_flag(obj, get_beta_info(obj), lines)
+
     if has_deprecated_params(obj):
         params = get_deprecated_params(obj)
         for param, info in params.items():

docs/sphinx/_ext/dagster-sphinx/dagster_sphinx/docstring_flags.py

@@ -3,7 +3,13 @@
 
 import dagster._check as check
 import docutils.nodes as nodes
-from dagster._annotations import DeprecatedInfo, ExperimentalInfo, PreviewInfo, SupersededInfo
+from dagster._annotations import (
+    BetaInfo,
+    DeprecatedInfo,
+    ExperimentalInfo,
+    PreviewInfo,
+    SupersededInfo,
+)
 
 from sphinx.util.docutils import SphinxDirective
 
@@ -16,7 +22,7 @@
 
 def inject_object_flag(
     obj: object,
-    info: Union[SupersededInfo, DeprecatedInfo, ExperimentalInfo, PreviewInfo],
+    info: Union[SupersededInfo, DeprecatedInfo, ExperimentalInfo, PreviewInfo, BetaInfo],
     docstring: list[str],
 ) -> None:
     if isinstance(info, DeprecatedInfo):
@@ -40,6 +46,13 @@ def inject_object_flag(
             f"This API is currently in preview, and may have breaking changes in patch version releases. "
             f"This API is not considered ready for production use.\n{additional_text}"
         )
+    elif isinstance(info, BetaInfo):
+        additional_text = f" {info.additional_warn_text}." if info.additional_warn_text else ""
+        flag_type = "beta"
+        message = (
+            f"This API is currently in beta, and may have breaking changes in minor version releases, "
+            f"with behavior changes in patch releases.\n{additional_text}"
+        )
     else:
         check.failed(f"Unexpected info type {type(info)}")
     for line in reversed([f".. flag:: {flag_type}", "", f"   {message}", ""]):

docs/sphinx/sections/api/apidocs/utilities.rst

@@ -17,6 +17,8 @@ Utilities
 
 .. autoclass:: dagster._utils.warnings.PreviewWarning
 
+.. autoclass:: dagster._utils.warnings.BetaWarning
+
 .. autofunction:: make_email_on_run_failure_sensor
 
 .. currentmodule:: dagster._utils.forked_pdb