Skip to content

Add TaskGroup markdown documentation support#67207

Draft
ytoprakc wants to merge 1 commit into
apache:mainfrom
ytoprakc:feat/add-task-group-doc-md
Draft

Add TaskGroup markdown documentation support#67207
ytoprakc wants to merge 1 commit into
apache:mainfrom
ytoprakc:feat/add-task-group-doc-md

Conversation

@ytoprakc
Copy link
Copy Markdown
Contributor

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.

Testing

Defining a .md filepath for doc_md

@task_group(
        group_id="data_extraction",
        tooltip="This group handles data extraction from various sources.",
        doc_md="/files/docs/example.md"
    )
    def data_extraction():
        ...
Screenshot 2026-05-19 at 20 51 30

Using docstrings when doc_md is not defined

@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.
        """
        ...
Screenshot 2026-05-19 at 20 50 21

If both doc_md and docstrings are available, doc_md takes precedence.

    @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.
        """
        ...
Screenshot 2026-05-19 at 20 57 11

Documentation is also available from the Grid View
Screenshot 2026-05-19 at 21 00 01


Was generative AI tooling used to co-author this PR?
  • Yes (please specify the tool below)

Generated-by: Codex following the guidelines

@ytoprakc ytoprakc marked this pull request as ready for review May 19, 2026 20:07
@ytoprakc ytoprakc marked this pull request as draft May 19, 2026 22:15
@ytoprakc ytoprakc force-pushed the feat/add-task-group-doc-md branch 3 times, most recently from 3091706 to aff4dea Compare May 22, 2026 07:55
@ytoprakc ytoprakc force-pushed the feat/add-task-group-doc-md branch from aff4dea to 946e941 Compare May 22, 2026 11:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add doc_md attribute to task groups

1 participant