Update code examples from "classic" operators to TaskFlow decorators in docs

[josh-fell]

Body

Related to #9415, which updates the code example DAGs to use the TaskFlow API, the documentation throughout should also reflect the same functional style for overall documentation alignment as well as encourage users and bring more visibility to these TaskFlow decorators.

Currently there are 3 core TaskFlow decorators can be used instead of their "classic" operator counterparts.

Classic Operator	TaskFlow Decorator
PythonOperator	@task
PythonVirtualenvOperator	@task.virtualenv
BranchPythonOperator	@task.branch

There are a number of doc files that could be updated to the TaskFlow equivalents of the "classic" operators:

• docs/apache-airflow/best-practices.rst
• docs/apache-airflow/faq.rst
• docs/apache-airflow/index.rst
• docs/apache-airflow/tutorial.rst
  • I'll be bold and say maybe there shouldn't be a "classic" tutorial and a TaskFlow API tutorial especially since the desire is to encourage TaskFlow and it's been 1.5 years since its release. Open to discuss this of course and what the community thinks here.
• docs/apache-airflow/concepts/dags.rst
• docs/apache-airflow/concepts/operators.rst
• docs/apache-airflow/concepts/params.rst
• docs/apache-airflow/howto/operator/python.rst
  • This should be refactored to _docs/apache-airflow/howto/decorators/python.rst. Add @task.short_circuit TaskFlow decorator #25752 is the last decorator implementation for Python operators. Once that is merged, we should refactor this page and fully sunset the operator doc.
• docs/apache-airflow/upgrading-from-1-10/index.rst

Committer

• I acknowledge that I am a maintainer/committer of the Apache Airflow project.

[hankehly]

Please assign this to me!

[josh-fell]

All yours! FYI, if you feel that these updates would be best done in multiple PRs that's totally fine.

[Bowrna]

@hankehly Could i take part of the issue if you don't mind? :) I am happy to help with this.

[hankehly]

Absolutely. Let's create a PR per file so we don't overlap

[Bowrna]

yeah sure @hankehly Please choose the files that you are taking and share it here. I will choose the ones that i will pick and share it too.

[hankehly]

#25657 updates the following

• docs/apache-airflow/best-practices.rst
• docs/apache-airflow/faq.rst
• docs/apache-airflow/index.rst

[Bowrna]

@hankehly I am picking up all the .rst files under folder docs/apache-airflow/concepts/ and making changes in the classic operators. Is that ok?