[GitHub] [airflow] potiuk commented on issue #26818: Not easy to know what is in context passed to operators and call_backs

[GitBox <gi...@apache.org>]

potiuk commented on issue #26818:
URL: https://github.com/apache/airflow/issues/26818#issuecomment-1264355596

   I think there are a few good points there.  But I think it is difficult to know if the documentation is enough. You can always say this should be "better described" or "clearer" or "better examples", but it is difficult to be judged by people who maintain it, so I mark it as a "good first issue" for someone who would like to pick that task and is a used.
   
   And in this context - I think you should attempt to provide a PR updating it. Airflow is creaed by > 2200 mostly people like you who miss something and then add it to either code or documentation or both. And I think you are one of the best people who know how and where people like would be searchig for such information.
   
   I am happy to guide you in the process @zazaho. Create PR and myself and others will be reviewing it and help you to make your first contribution. Also this is great opportunity to actually pay back for the free software you use and join the people who - mostly in their free time - contribute to airflow.
   
   You can go to https://airflow.apache.org/docs/apache-airflow/stable/templates-ref.html and click "Suggest a change on this page" button and you will be able to open PR where you can update the docs. Same with other changes. 
   
   It is all rather easy - you just need to see how other .rst files in our documentation - even if you do not know .rst syntax. You can refer to classes such as TaskInstance (you will find in other .rst files how to refer to classes, you can add explanation, you can also add some examples (also see how it is done in other .rst. 
   
   And you can also find some more information about the Context class here: https://github.com/apache/airflow/blob/main/airflow/utils/context.pyi. where the context typing is decribed in Python typing mode - it is used for autocomplete when you use context in other 
   
   From your description I think you could add:
   
   * paragraph in "templates-red" that those fields here describe context passed elsewhere (and possibly list all those places like operators and callbacks)
   
   * add some examples (maybe from your real dags - that woudl be best if you can do it as you likely already have some good examples you can provide) 
   
   * Explain that context is defined in Context.pyi for those curious and that with modern IDE they can get it autocomplete'able
   
   * maybe even you could add dosctrings in the Context.pyi to get the documentation directly there - that could help those who use autocomplete
   
   Adding such documentation is also a great opportunity to learn - you might find other places where things are documented (for example ds etc. are likely described in Scheduling section) and bring the explanation from there to the reference.
   
   
   Lookling forward to such contribution (and even if not you, then maybe someone will be able to pick that one up and make nice PRs clarifying all those).
   
   
   


-- 
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: commits-unsubscribe@airflow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org