From 03762ee798c28c20ac3496ffe2b7136bc42ca368 Mon Sep 17 00:00:00 2001
From: Jarek Potiuk <jarek@potiuk.com>
Date: Tue, 2 May 2023 19:00:28 +0200
Subject: [PATCH] Fix missing models in API documentation.

The Airflow models have been accidentally removed from the docs
when #28300 was implemented. The whole models documentation have
been removed accidentally, even if there were references to the
actual classes and packages used as the models package was
entirely excluded.

This PR fixes it by selectively including the models that should
be included and by linking the package indexes directly in
the public interface documentation.
---
 airflow/models/taskinstance.py                |  2 +-
 .../public-airflow-interface.rst              | 54 ++++++++++++++++++-
 docs/conf.py                                  | 18 +++++++
 docs/spelling_wordlist.txt                    |  1 +
 4 files changed, 73 insertions(+), 2 deletions(-)

diff --git a/airflow/models/taskinstance.py b/airflow/models/taskinstance.py
index e97a5af2a80d7..fa1e50b1916e4 100644
--- a/airflow/models/taskinstance.py
+++ b/airflow/models/taskinstance.py
@@ -214,7 +214,7 @@ def clear_task_instances(
     :param tis: a list of task instances
     :param session: current session
     :param dag_run_state: state to set finished DagRuns to.
-    If set to False, DagRuns state will not be changed.
+        If set to False, DagRuns state will not be changed.
     :param dag: DAG object
     :param activate_dag_runs: Deprecated parameter, do not pass
     """
diff --git a/docs/apache-airflow/public-airflow-interface.rst b/docs/apache-airflow/public-airflow-interface.rst
index 4718d18b54004..6d36de5df19df 100644
--- a/docs/apache-airflow/public-airflow-interface.rst
+++ b/docs/apache-airflow/public-airflow-interface.rst
@@ -58,7 +58,9 @@ DAGs
 ----
 
 The DAG is Airflow's core entity that represents a recurring workflow. You can create a DAG by
-instantiating the :class:`~airflow.models.dag.DAG` class in your DAG file.
+instantiating the :class:`~airflow.models.dag.DAG` class in your DAG file. You can also instantiate
+them via :class::`~airflow.models.dagbag.DagBag` class that reads DAGs from a file or a folder. DAGs
+can also have parameters specified via :class::`~airflow.models.param.Param` class.
 
 Airflow has a set of example DAGs that you can use to learn how to write DAGs
 
@@ -73,6 +75,17 @@ You can read more about DAGs in :doc:`DAGs <core-concepts/dags>`.
 
 .. _pythonapi:operators:
 
+References for the modules used in DAGs are here:
+
+.. toctree::
+  :includehidden:
+  :glob:
+  :maxdepth: 1
+
+  _api/airflow/models/dag/index
+  _api/airflow/models/dagbag/index
+  _api/airflow/models/param/index
+
 Operators
 ---------
 
@@ -114,6 +127,30 @@ Also you can learn how to write a custom operator in :doc:`howto/custom-operator
 
 .. _pythonapi:hooks:
 
+References for the modules used in for operators are here:
+
+.. toctree::
+  :includehidden:
+  :glob:
+  :maxdepth: 1
+
+  _api/airflow/models/baseoperator/index
+
+
+Task Instances
+--------------
+
+Task instances are the individual runs of a single task in a DAG (in a DAG Run). They are available in the context
+passed to the execute method of the operators via the :class:`~airflow.models.taskinstance.TaskInstance` class.
+
+.. toctree::
+  :includehidden:
+  :glob:
+  :maxdepth: 1
+
+  _api/airflow/models/taskinstance/index
+
+
 Hooks
 -----
 
@@ -144,6 +181,19 @@ use the following classes:
 You can read more about the public Airflow utilities in :doc:`howto/connection`,
 :doc:`core-concepts/variables`, :doc:`core-concepts/xcoms`
 
+
+Reference for classes used for the utilities are here:
+
+.. toctree::
+  :includehidden:
+  :glob:
+  :maxdepth: 1
+
+  _api/airflow/models/connection/index
+  _api/airflow/models/variable/index
+  _api/airflow/models/xcom/index
+
+
 Public Exceptions
 -----------------
 
@@ -348,6 +398,8 @@ Airflow can help track origins of data, what happens to it and where it moves ov
 about lineage in :doc:`administration-and-deployment/lineage`.
 
 
+
+
 What is not part of the Public Interface of Apache Airflow?
 ===========================================================
 
diff --git a/docs/conf.py b/docs/conf.py
index fb6c82c25bd93..5e0f81474aa83 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -228,6 +228,7 @@ def _get_rst_filepath_from_path(filepath: pathlib.Path):
         "decorators",
         "example_dags",
         "executors",
+        "models",
         "operators",
         "providers",
         "secrets",
@@ -238,6 +239,17 @@ def _get_rst_filepath_from_path(filepath: pathlib.Path):
     }
     browsable_utils: set[str] = set()
 
+    models_included: set[str] = {
+        "baseoperator.py",
+        "connection.py",
+        "dag.py",
+        "dagbag.py",
+        "param.py",
+        "taskinstance.py",
+        "variable.py",
+        "xcom.py",
+    }
+
     root = ROOT_DIR / "airflow"
     for path in root.iterdir():
         if path.is_file() and path.name not in _allowed_top_level:
@@ -249,6 +261,12 @@ def _get_rst_filepath_from_path(filepath: pathlib.Path):
     for path in (root / "utils").iterdir():
         if path.name not in browsable_utils:
             exclude_patterns.append(_get_rst_filepath_from_path(path))
+
+    for path in (root / "models").iterdir():
+        if path.name not in models_included:
+            exclude_patterns.append(_get_rst_filepath_from_path(path))
+
+
 elif PACKAGE_NAME != "docker-stack":
     exclude_patterns.extend(
         _get_rst_filepath_from_path(f) for f in pathlib.Path(PACKAGE_DIR).glob("**/example_dags")
diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt
index 5bceb55944194..dc4da70a26524 100644
--- a/docs/spelling_wordlist.txt
+++ b/docs/spelling_wordlist.txt
@@ -331,6 +331,7 @@ dagbags
 DagCallbackRequest
 DagFileProcessorManager
 dagmodel
+DagParam
 Dagre
 dagre
 DagRun