Example DAGs are missing DAG-level documentation (doc_md) in the UI #60128
Description
What do you see as an issue?
Description
While exploring the example DAGs shipped with Apache Airflow, I noticed that many of them
do not include DAG-level markdown documentation (doc_md).
As a result, when these example DAGs are viewed in the Airflow UI, the Docs tab is empty,
which makes it harder for new users to understand what each example is demonstrating.
In contrast, tutorial DAGs such as tutorial_taskflow_api.py provide clear, helpful
documentation that greatly improves the learning experience.
Examples
Some example DAGs that currently lack doc_md include:
- example_sensor_decorator.py
- example_short_circuit_decorator.py
- example_bash_decorator.py
- example_branch_operator_decorator.py
(This list is not exhaustive.)
Proposed improvement
Add concise DAG-level documentation (doc_md) to example DAGs, following the same style
used in tutorial DAGs. This would make example DAGs more self-explanatory and easier to
learn from directly in the UI.
I am happy to work on this improvement and submit incremental PRs if the approach
sounds reasonable.
Additional context
This would be a documentation-only change and would not affect runtime behavior.
Solving the problem
The documentation can be improved by adding concise DAG-level markdown documentation
(doc_md) to example DAGs that currently do not provide any content in the Docs
tab of the Airflow UI.
Specifically, this documentation should be added directly to the DAG definition
(either in the @dag decorator or the DAG(...) constructor) for example DAGs
located under:
providers/standard/src/airflow/providers/standard/example_dags/
Each example DAG should include a short markdown section explaining:
- What the example DAG demonstrates
- Which operator or decorator it focuses on
- Any important behavior (e.g. branching, short-circuiting, sensors)
- A link to the relevant section of the official Airflow documentation
This approach is already used successfully in tutorial DAGs such as
tutorial_taskflow_api.py, and applying the same pattern to example DAGs would
make them much more self-explanatory when viewed directly in the UI.
The change would be documentation-only and would not affect DAG execution or
runtime behavior.
Anything else
This issue primarily affects new users and contributors who explore example DAGs
via the Airflow UI. When the Docs tab is empty, users need to inspect the source
code directly to understand the purpose of the DAG, which increases the learning
curve.
Providing DAG-level documentation would improve usability and consistency across
example and tutorial DAGs.
Are you willing to submit PR?
- Yes I am willing to submit a PR!
Code of Conduct
- I agree to follow this project's Code of Conduct