Skip to content

Set doc_md on TaskFlow decorator example DAGs#66443

Open
ColtenOuO wants to merge 1 commit intoapache:mainfrom
ColtenOuO:add-doc-md-to-decorator-example-dags
Open

Set doc_md on TaskFlow decorator example DAGs#66443
ColtenOuO wants to merge 1 commit intoapache:mainfrom
ColtenOuO:add-doc-md-to-decorator-example-dags

Conversation

@ColtenOuO
Copy link
Copy Markdown
Contributor

Summary

Closes #60128 by setting dag.doc_md on three TaskFlow-decorator example DAGs in providers/standard/src/airflow/providers/standard/example_dags/. Without doc_md, the DAG's "Docs" tab in the UI is empty, which hurts the first-time-user / onboarding experience these examples are meant to support.

The issue body names four examples as a starting set. One of them — example_bash_decorator.py — already has a function-level docstring, which the @dag decorator auto-assigns to dag.doc_md when no explicit doc_md is set, so its Docs tab is already populated and it's intentionally left out of this PR.

The remaining three from the issue's starting set are addressed:

File Pattern Change
example_sensor_decorator.py @dag decorator, only a module docstring Added a function docstring (auto-flows into doc_md)
example_short_circuit_decorator.py @dag decorator, only a module docstring Added a function docstring (auto-flows into doc_md)
example_branch_operator_decorator.py with DAG(...) block, module docstring Restructured the existing module docstring as Markdown and passed doc_md=__doc__ to the DAG(...) call

Each doc_md follows the structure called out in the issue: H3 title, one-paragraph intro, a "What this DAG shows" bulleted list, and a link to the relevant operator/concept docs.

Was generative AI tooling used to co-author this PR?
  • Yes (Claude Code) for grammar correction

Generated-by: Claude Code following the guidelines

@ColtenOuO
Copy link
Copy Markdown
Contributor Author

The stable/operators/python.html URL on apache.org currently returns 404 in browsers due to a meta-refresh redirect to a stale archive path.

I followed the existing in-directory convention from example_bash_operator.py (no link) rather than ship dead URLs.

Happy to add links in a follow-up once the redirect is fixed.

@ColtenOuO
Copy link
Copy Markdown
Contributor Author

The failing job Low dep tests: providers / All-prov:LowestDeps:14:3.10:mongo...samba looks unrelated to this PR — it fails with pymongo.errors.ServerSelectionTimeoutError: 172.17.0.1:32769: [Errno 111] Connection refused, i.e. the MongoDB container in CI didn't accept connections. This PR only touches three example DAG files in providers/standard/src/airflow/providers/standard/example_dags/, which have no MongoDB dependency.

Could a maintainer rerun the failed job? Happy to push an empty commit if that's preferred.

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.

Example DAGs are missing DAG-level documentation (doc_md) in the UI

1 participant