Example Operator usage does not include `import` statements

[jroachgolf84]

What do you see as an issue?

When a user is leveraging our Operator docs (such as for the BashOperator: https://airflow.apache.org/docs/apache-airflow-providers-standard/stable/operators/bash.html), each code snippet "stands alone" in the sense that there are no import statements as part of the code block. In fact, there is no reference to where this Operator can be imported from. This is due to using something like the following in our documentation.

  .. exampleinclude:: /../../../airflow-core/src/airflow/example_dags/example_bash_operator.py
      :language: python
      :dedent: 4
      :start-after: [START howto_operator_bash]
      :end-before: [END howto_operator_bash]

Solving the problem

I think there are a couple of ways that we could solve this problem. However, I believe that it warrants more discussion, as this would be something that needs to be solved across almost every provider. I think the easiest would be including a snippet at the top of each page that includes where the Operator/Hook/Sensors etc. can be imported from, rather than redundantly adding an import statement to each code snippet.

Anything else

No response

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

[potiuk]

There used to be link where you could go to sources directly from the example - see for example here https://airflow.apache.org/docs/apache-airflow/2.10.0/howto/operator/time.html#howto-operator-timedeltasensor - likely it's broken now when the operators moved to standard provider, but this should be fixed.

[potiuk]

Yeah . I think it was broken very recently.

[potiuk]

You can see for example https://airflow.apache.org/docs/apache-airflow-providers-google/15.1.0/operators/cloud/bigtable.html -> and go to previous version of the google operator.

[jroachgolf84]

@potiuk, do you think it makes sense to re-scope this issue to point users back to the source? I still think there would be a use-case for including the import statement somewhere in the example itself (not necessarily within the code snippet tho).

[potiuk]

@potiuk, do you think it makes sense to re-scope this issue to point users back to the source? I still think there would be a use-case for including the import statement somewhere in the example itself (not necessarily within the code snippet tho).

Yes. I think it should be fixed to the previous setting. If you think you can propose a solution that will do it differently - you are absolutely free to make PR showing it without even having an issue. We absolutely do not need issues to make changes - we need someone who will make the changes and contribute them as PR