Documentation guidelines about airflow HOT 5 CLOSED

There's a special undocumented feature to squeeze documentation at a task level. All you need to do is

foo = SomeOperator(...)
foo.doc = "This task does nothing"

This will render in the "Task Details" page in the header section.

There's also task.doc_yaml and task.doc_json that will actually render using nice language aware color coding. I could easily add task.doc_markup and/or task.doc_rst.

We could add more hook, say at the DAG level too and render it somewhere (as a header in the Graph view?). Though for now if you put a docstring on your DAG module you'll see it in the "Code" view.

from airflow.

#74

from airflow.

This looks brilliant! Is there also a way of using the ``.doc` attribute in something like sphynx or at least some way of getting such comments out of the airflow ecosystem for use in a doc library for developers?

from airflow.

Not sure, the sphinx automagic works out of class doctrings, not object content.

But it would be easy to put something together in the DAG object that would gather the doc_md string from the DAG object and all the tasks in the DAG and put together some a raw html page.

from airflow.

I'm closing this for now, but it shouldn't be hard to create a DAG.generate_html_docs() method at this point. I won't be writing it myself since we use the Airflow UI to display the eventual docs.

from airflow.