Add state utils to Public Airflow Interface

The state enums are likely to be used externally and they should
not be changed in backwards-incompatible way.

Discussed in apache#33746

airflow/utils/state.py

@@ -80,7 +80,7 @@ def __str__(self) -> str:
 
 
 class State:
-    """Static class with task instance state constants and color methods to avoid hardcoding."""
+    """Static class with task instance state constants and color methods to avoid hard-coding."""
 
     # Backwards-compat constants for code that does not yet use the enum
     # These first three are shared by DagState and TaskState

docs/apache-airflow/public-airflow-interface.rst

@@ -222,6 +222,16 @@ exposes:
 
   _api/airflow/exceptions/index
 
+Public Utility classes
+----------------------
+
+.. toctree::
+  :includehidden:
+  :glob:
+  :maxdepth: 1
+
+  _api/airflow/utils/state/index
+
 
 Using Public Interface to extend Airflow capabilities
 =====================================================

docs/conf.py

@@ -236,7 +236,9 @@ def _get_rst_filepath_from_path(filepath: pathlib.Path):
         "triggers",
         "utils",
     }
-    browsable_utils: set[str] = set()
+    browsable_utils: set[str] = {
+        "state.py",
+    }
 
     models_included: set[str] = {
         "baseoperator.py",
@@ -257,7 +259,7 @@ def _get_rst_filepath_from_path(filepath: pathlib.Path):
         if path.is_dir() and path.name not in browsable_packages:
             exclude_patterns.append(f"_api/airflow/{path.name}")
 
-    # Don't include all of utils, just the specific ones we decoded to include
+    # Don't include all of utils, just the specific ones we decided to include
     for path in (root / "utils").iterdir():
         if path.name not in browsable_utils:
             exclude_patterns.append(_get_rst_filepath_from_path(path))