docs: Enhance triggering_asset_event retrieval documentation in DAGs (#52666)

[prdai]

Closes: #52666

This pull request enhances the Airflow documentation around fetching and using the triggering_asset_events context variable in DAGs. It provides clearer guidance and real‐world examples to improve authoring and scheduling workflows.

What’s Changed

• Jinja Templating Examples

  • Added a “Single Triggering Asset” snippet demonstrating how to access the first AssetEvent via {{ triggering_asset_events.values() | first | first }}.
  • Provided a “Multiple Triggering Assets” loop example to iterate over all assets and their events in BashOperator templates.

• Python Task Examples

  • Included a Python @task function showing direct access to triggering_asset_events as a parameter, with illustrative prints for event.source_dag_run.* attributes.

• Structural Clarifications

  • Explained that triggering_asset_events is a dict[AssetURI, list[AssetEvent]] and outlined best practices for handling multiple events per asset.

• Edge-Case Note

  • Added a warning about complexity when a DAG is scheduled by multiple assets or when assets are updated multiple times before consumption, suggesting strategies for bespoke processing logic.

Why This Matters

Clear, example-driven documentation reduces onboarding friction for users authoring asset-driven DAGs and prevents misinterpretation of the triggering_asset_events API surface.

[boring-cyborg]

Congratulations on your first Pull Request and welcome to the Apache Airflow community! If you have any issues or are unsure about any anything please check our Contributors' Guide (https://github.com/apache/airflow/blob/main/contributing-docs/README.rst)
Here are some useful points:

• Pay attention to the quality of your code (ruff, mypy and type annotations). Our pre-commits will help you with that.
• In case of a new feature add useful documentation (in docstrings or in docs/ directory). Adding a new operator? Check this short guide Consider adding an example DAG that shows how users should use it.
• Consider using Breeze environment for testing locally, it's a heavy docker but it ships with a working Airflow and a lot of integrations.
• Be patient and persistent. It might take some time to get a review or get the final approval from Committers.
• Please follow ASF Code of Conduct for all communication including (but not limited to) comments on Pull Requests, Mailing list and Slack.
• Be sure to read the Airflow Coding style.
• Always keep your Pull Requests rebased, otherwise your build might fail due to changes not related to your commits.
  Apache Airflow is a community-driven project and together we are making it better 🚀.
  In case of doubts contact the developers at:
  Mailing List: dev@airflow.apache.org
  Slack: https://s.apache.org/airflow-slack

[vincbeck]

Looks good! Static checks are failing. Please run pre-commits to fix them. Documentation

[Copilot]

Pull Request Overview

This PR enhances the documentation for accessing triggering_asset_events in Airflow DAGs by adding clearer explanations and practical examples.

• Expanded the description of triggering_asset_events with a Python-style dictionary snippet showing its structure.
• Added Jinja templating examples for single and multiple asset triggers, including iteration patterns.
• Provided a Python @task example demonstrating direct access to the context variable and noted edge-case handling strategies.

Comments suppressed due to low confidence (4)

airflow-core/docs/authoring-and-scheduling/asset-scheduling.rst:153

• [nitpick] Consider using a more specific code-block language (e.g., 'jinja' or 'bash') for the Jinja templating examples to improve syntax highlighting and clarity.

.. code-block:: python

airflow-core/docs/authoring-and-scheduling/asset-scheduling.rst:185

• [nitpick] Ensure the Jinja example code block is labeled appropriately (e.g., 'bash') since it contains BashOperator commands and Jinja syntax.

.. code-block:: python

airflow-core/docs/authoring-and-scheduling/asset-scheduling.rst:233

• [nitpick] Ensure the Python code block for the @task example has consistent indentation for the function body and decorator placement to improve readability.

.. code-block:: python

airflow-core/docs/authoring-and-scheduling/asset-scheduling.rst:155

• [nitpick] Consider adding a reference link to the AssetEvent API documentation for attributes like source_dag_run and timestamp to help readers explore available properties.

    {

[github-actions]

This pull request has been automatically marked as stale because it has not had recent activity. It will be closed in 5 days if no further activity occurs. Thank you for your contributions.

[github-actions]

Backport successfully created: v3-1-test

Status	Branch	Result
✅	v3-1-test