Addressed some issues in the tutorial mentioned in discussion #22233

[MattTriano]

While working through the tutorial, some parts seemed a bit unclear or incorrect, which took me to issue #18950 ( converted into discussion #22233 about 15 minutes ago). I had already resolved some of the open concerns and saw potiuk encouraging people to improve the documentation, so I took it upon myself.

Main Changes:

• Wrote tasks to handle db-table-creation in the DAG rather than leave that as an exercise for the reader.
• Added a step to ensure the existence of the data output directory in the get_data() task.
• Fixed the logic in the merge_data() task so that its behavior matches the stated description.

---

^ Add meaningful description above

Read the Pull Request Guidelines for more information.
In case of fundamental code change, Airflow Improvement Proposal (AIP) is needed.
In case of a new dependency, check compliance with the ASF 3rd Party License Policy.
In case of backwards incompatible changes please leave a note in UPDATING.md.

[boring-cyborg]

Congratulations on your first Pull Request and welcome to the Apache Airflow community! If you have any issues or are unsure about any anything please check our Contribution Guide (https://github.com/apache/airflow/blob/main/CONTRIBUTING.rst)
Here are some useful points:

• Pay attention to the quality of your code (flake8, mypy and type annotations). Our pre-commits will help you with that.
• In case of a new feature add useful documentation (in docstrings or in docs/ directory). Adding a new operator? Check this short guide Consider adding an example DAG that shows how users should use it.
• Consider using Breeze environment for testing locally, it’s a heavy docker but it ships with a working Airflow and a lot of integrations.
• Be patient and persistent. It might take some time to get a review or get the final approval from Committers.
• Please follow ASF Code of Conduct for all communication including (but not limited to) comments on Pull Requests, Mailing list and Slack.
• Be sure to read the Airflow Coding style.
  Apache Airflow is a community-driven project and together we are making it better 🚀.
  In case of doubts contact the developers at:
  Mailing List: dev@airflow.apache.org
  Slack: https://s.apache.org/airflow-slack

[MattTriano]

I spent a bit more time refactoring (after noticing a thought I left incomplete). I assume most tutorial readers are either trying to get things running on their machine or are evaluating whether it's worth taking the time to try, so I tried to make the example terse but still be batteries-included.

Main changes:

• I explicitly listed setup commands
• I moved service startup instructions in front of connection creation instructions
• I refined descriptions of the task development steps,
• I tried to use phrasing consistent with other documentation pages,
• I included links to help readers discover a convenient workflow (eg that updates to DAGs in code on the host machine (but still in the dags/ dir) would be discovered after a delay without needing to restart any services).

[potiuk]

Love the attention to details !

[potiuk]

Thanks @MattTriano -> let's see how the CI likes it :)

[github-actions]

The PR is likely ready to be merged. No tests are needed as no important environment files, nor python files were modified by it. However, committers might decide that full test matrix is needed and add the 'full tests needed' label. Then you should rebase it to the latest main or amend the last commit of the PR, and push it with --force-with-lease.

[MattTriano]

 ------------------------------ Error   1 --------------------
 WARNING: Block quote ends without a blank line; unexpected unindent.

File path: apache-airflow/tutorial.rst (548)

 545 | And from the last line in the definition of the ``Etl`` DAG, we see:
 546 | 
 547 |   >> get_data() >> merge_data()
>548 | * the ``merge_data()`` task depends on the ``get_data()`` task,
------------------------------ Error   2 --------------------
 ERROR: Unknown target name: "brief delay<https://airflow.apache.org/docs/apache-airflow/stable/configurations-ref.html#dag-dir-list-interval>".

These errors caused the Build docs CI job to fail. Technically it also threw a spelling error, but the only error traceback from the Output of spelling check: apache-airflow section pointed to line 548 citing the lack of a blank line or unindentation. I'm confident I handled that correctly in my latest commit.

For Error 2, I think the issue was the lack of whitespace between the text and the bracketed-URI, but I'm not too familiar with the reStructuredText spec, so it's possible that I'm wrong and wasting more compute.

[potiuk]

For Error 2, I think the issue was the lack of whitespace between the text and the bracketed-URI, but I'm not too familiar with the reStructuredText spec, so it's possible that I'm wrong and wasting more compute.

You can run it locally (see the error output - it explains what commands you can run to build the docs locally)

[MattTriano]

What a ./breeze (...build-docs -- --spellcheck-only --package-filter apache-airflow) that was.

[boring-cyborg]

Awesome work, congrats on your first merged pull request!

[potiuk]

Thanks! Really cool!