ytoprakc opened a new pull request, #67207:
URL: https://github.com/apache/airflow/pull/67207
### Description
This PR adds doc_md support for TaskGroups, allowing authors to document a
TaskGroup at the same level of abstraction shown in the Dag graph and Grid
views.
TaskGroups can now define markdown documentation directly or by referencing
a .md file, and that documentation is serialized with the Dag, exposed through
the UI structure APIs, and rendered from the TaskGroup details panel.
### Changes
- Add doc_md to TaskGroup definitions and the @task_group decorator.
- Support .md file resolution for TaskGroup doc_md, matching Dag doc_md
behaviour.
- Preserve explicit doc_md when a decorated TaskGroup function also has a
docstring.
- Serialize and deserialize TaskGroup doc_md.
- Include TaskGroup doc_md in graph and Grid structure responses.
- Render TaskGroup documentation in the details panel using the existing
markdown documentation modal.
- Add the translated modal title: Task Group Documentation.
- Update generated UI API types and schemas.
- Document TaskGroup doc_md usage.
- Add tests for SDK behavior, file resolution, serialization, and UI
structure responses.
### Why
TaskGroups are often the right level of abstraction for explaining a Dag to
non-technical stakeholders. Before this change, documentation could be attached
to a Dag or individual tasks, but not to the TaskGroup that represents a
higher-level operation. This lets Dag authors provide concise summaries for
grouped operations without requiring users to drill into task-level details.
* closes: #65679
### Testing
**Defining a `.md` filepath for `doc_md`**
```python
@task_group(
group_id="data_extraction",
tooltip="This group handles data extraction from various sources.",
doc_md="/files/docs/example.md"
)
def data_extraction():
...
```
<img width="1920" height="956" alt="Screenshot 2026-05-19 at 20 51 30"
src="https://github.com/user-attachments/assets/2a8d236b-3c07-4fb1-b991-3ce8987d6c70";
/>
---
**Using docstrings when `doc_md` is not defined**
```python
@task_group(
group_id="data_extraction",
tooltip="This group handles data extraction from various sources."
)
def data_extraction():
"""
# Docs for Data Extraction Task Group
- This is an example doc from the docstrings.
"""
...
```
<img width="1920" height="959" alt="Screenshot 2026-05-19 at 20 50 21"
src="https://github.com/user-attachments/assets/e81ee942-a436-4c54-a090-1936ba74c3b7";
/>
---
**If both `doc_md` and docstrings are available, `doc_md` takes precedence.**
```python
@task_group(
group_id="data_extraction",
tooltip="This group handles data extraction from various sources.",
doc_md="""# Data Extraction Task Group\n- This is an example doc
from doc_md."""
)
def data_extraction():
"""
# Docs for Data Extraction Task Group
- This is an example doc from the docstrings.
"""
...
```
<img width="1920" height="958" alt="Screenshot 2026-05-19 at 20 57 11"
src="https://github.com/user-attachments/assets/e3066de3-fafc-428c-85ed-af2fe5989f5c";
/>
---
**Documentation is also available from the Grid View**
<img width="1920" height="959" alt="Screenshot 2026-05-19 at 21 00 01"
src="https://github.com/user-attachments/assets/e071947a-d53f-4d45-8668-f6942253b251";
/>
---
##### Was generative AI tooling used to co-author this PR?
<!--
If generative AI tooling has been used in the process of authoring this PR,
please
change below checkbox to `[X]` followed by the name of the tool, uncomment
the "Generated-by".
-->
- [x] Yes (please specify the tool below)
Generated-by: Codex following [the
guidelines](https://github.com/apache/airflow/blob/main/contributing-docs/05_pull_requests.rst#gen-ai-assisted-contributions)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
