[docs] display preview warning and decorator info (#26819)

## Summary & Motivation

Same as #25362 but for the new preview decorator introduced in
#26747

docs/content/about/releases.mdx

@@ -23,6 +23,12 @@ The "experimental" marker allows us to offer new APIs to users and rapidly itera
 
 Experimental APIs may change or disappear within any release, but we try to avoid breaking them within minor releases if they have been around for a long time.
 
+### Preview APIs
+
+The "preview" marker allows us to offer APIs in early testing phase to users and rapidly iterate based on their feedback. Preview APIs are marked as such in the [API reference](/\_apidocs) and usually raise a <PyObject object="PreviewWarning" module="dagster._utils.warnings" /> when used.
+
+Preview APIs may change or disappear within any release and are not considered ready for production use.
+
 ### 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

@@ -280,6 +280,7 @@ We've also got a bunch of badges that you can use to indicate the level of suppo
 There are the available badges:
 
 - `{% experimental /%}` {% experimental /%}
+- `{% preview /%}` {% preview /%}
 - `{% deprecated /%}` {% deprecated /%}
 - `{% superseded /%}` {% superseded /%}
 - `{% legacy /%}` {% legacy /%}

docs/next/components/markdoc/Badges.tsx

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

docs/next/components/mdx/MDXComponents.tsx

@@ -429,6 +429,18 @@ const Experimental = () => {
   );
 };
 
+////////////////////////
+//  Preview BADGE  //
+////////////////////////
+
+const Preview = () => {
+  return (
+      <div className="preview-tag">
+        <span className="hidden">(</span>Preview<span className="hidden">)</span>
+      </div>
+  );
+};
+
 ////////////////////////
 //  DEPRECATED BADGE  //
 ////////////////////////
@@ -866,6 +878,7 @@ export default {
   Experimental,
   Deprecated,
   Superseded,
+  Preview,
   Legacy,
   Icons,
   ReferenceTable,

docs/next/markdoc/tags.js

@@ -1,5 +1,5 @@
 import {ArticleList, ArticleListItem} from '../components/markdoc/ArticleList';
-import {Badge, Experimental, Deprecated, Superseded, Legacy} from '../components/markdoc/Badges';
+import {Badge, Experimental, Preview, 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';
@@ -80,6 +80,11 @@ export const experimental = {
   selfClosing: true,
 };
 
+export const preview = {
+  render: Preview,
+  selfClosing: true,
+};
+
 export const deprecated = {
   render: Deprecated,
   selfClosing: true,

docs/next/styles/globals.css

@@ -104,6 +104,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
 }
 
+.preview-tag,
+.flag.preview {
+  @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

@@ -6,11 +6,13 @@
     get_deprecated_params,
     get_experimental_info,
     get_experimental_params,
+    get_preview_info,
     get_superseded_info,
     has_deprecated_params,
     has_experimental_params,
     is_deprecated,
     is_experimental,
+    is_preview,
     is_public,
     is_superseded,
 )
@@ -126,6 +128,9 @@ def process_docstring(
     if is_superseded(obj):
         inject_object_flag(obj, get_superseded_info(obj), lines)
 
+    if is_preview(obj):
+        inject_object_flag(obj, get_preview_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,7 @@
 
 import dagster._check as check
 import docutils.nodes as nodes
-from dagster._annotations import DeprecatedInfo, ExperimentalInfo, SupersededInfo
+from dagster._annotations import DeprecatedInfo, ExperimentalInfo, PreviewInfo, SupersededInfo
 
 from sphinx.util.docutils import SphinxDirective
 
@@ -15,7 +15,9 @@
 
 
 def inject_object_flag(
-    obj: object, info: Union[SupersededInfo, DeprecatedInfo, ExperimentalInfo], docstring: list[str]
+    obj: object,
+    info: Union[SupersededInfo, DeprecatedInfo, ExperimentalInfo, PreviewInfo],
+    docstring: list[str],
 ) -> None:
     if isinstance(info, DeprecatedInfo):
         additional_text = f" {info.additional_warn_text}." if info.additional_warn_text else ""
@@ -31,6 +33,13 @@ def inject_object_flag(
         additional_text = f" {info.additional_warn_text}." if info.additional_warn_text else ""
         flag_type = "superseded"
         message = f"This API has been superseded and its usage is discouraged.\n{additional_text}"
+    elif isinstance(info, PreviewInfo):
+        additional_text = f" {info.additional_warn_text}." if info.additional_warn_text else ""
+        flag_type = "preview"
+        message = (
+            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}"
+        )
     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

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