kalel-commits opened a new issue, #60128: URL: https://github.com/apache/airflow/issues/60128
### 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? - [x] Yes I am willing to submit a PR! ### Code of Conduct - [x] I agree to follow this project's [Code of Conduct](https://github.com/apache/airflow/blob/main/CODE_OF_CONDUCT.md) -- 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]
