[docs] Add deprecated/experimental flags and warnings to docs

[smackesey]

Summary & Motivation

#15077 introduced special rendering of "Deprecated" tags in the docs. This PR expands that effort by leveraging the downstack consolidation of deprecated/experimental warnings into the annotations layer (#15302, #15305). With the decorator APIs for warnings, one declaration is sufficient to specify information for both the docs and a runtime warning.

This PR makes @deprecated, @deprecated_param, @experimental, and @experimental_param render a special tag and associated warning text in the docs. Examples:

    @public
    @deprecated(
        breaking_version="2.0",
        additional_warn_text="Setting this property no longer has any effect.",
    )
    @property
    def environment_vars(self) -> Mapping[str, str]:
        """Mapping[str, str]: Environment variables to export to the cron schedule."""
        return self._environment_vars

    @public
    @staticmethod
    @experimental
    def table(
        records: Sequence[TableRecord], schema: Optional[TableSchema] = None
    ) -> "TableMetadataValue":
        """Static constructor for a metadata value wrapping arbitrary tabular data as
        :py:class:`TableMetadataValue`. Can be used as the value type for the `metadata`
        parameter for supported events.

@experimental_param(param="resource_defs")
@experimental_param(param="io_manager_def")
@experimental_param(param="auto_materialize_policy")
@deprecated_param(
    param="non_argument_deps", breaking_version="2.0.0", additional_warn_text="use `deps` instead."
)
def asset(
    compute_fn: Optional[Callable] = None,
    *,
    name: Optional[str] = None,
    key_prefix: Optional[CoercibleToAssetKeyPrefix] = None,
    ins: Optional[Mapping[str, AssetIn]] = None,
    deps: Optional[Sequence[Union[CoercibleToAssetKey, AssetsDefinition, SourceAsset]]] = None,

As a result of this, it is no longer necessary to describe an entity as deprecated/experimental in its docstring-- that info will come from the decorator. So this PR also removes some of this info from docstrings.

The bulk of the code for this is in the sphinx extension, but I also added some CSS and a new color for the "experimental" tags. Happy to go with other styling suggestions.

How I Tested These Changes

Built docs.

[smackesey]

Current dependencies on/for this PR:

• master
  • PR [refactor] autodoc_dagster.py -> dagster-sphinx #15407
    • PR dagit-screenshot -> dagster-ui-screenshot #15408
    • PR [docs] Add deprecated/experimental flags and warnings to docs #15311 👈

This comment was auto-generated by Graphite.

[github-actions]

Deploy preview for dagster ready!

Preview available at https://dagster-o2adx9lwt-elementl.vercel.app

Direct link to changed pages:

[github-actions]

Deploy preview for dagster-docs ready!

Preview available at https://dagster-docs-kdbtpmgwz-elementl.vercel.app
https://sean-docs-add-flags.dagster.dagster-docs.io

Direct link to changed pages:

[erinkcochran87]

Overall I like this a lot! It's so much easier to identify non-stable/unavailable things now. No qualms with the approach or how it's implemented.

On styling, however, I have a few thoughts:

• Nitpick - The box containing the the API-level deprecation (the first example in the PR description) doesn't line up with the text that follows it - it's slightly more to the right. It'd be super if the box/callout and text could be in line with each other.
• The UI has styles for labels similar to these - should we use that styling (or similar) to be consistent? Ex:
  

[smackesey]

On styling, however, I have a few thoughts:

@hellendag is going to do a followup PR to correct the styling