[airflow] branch master updated: Small changes on "DAGs and Tasks documentation" (#14853)

[po...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

potiuk pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/airflow.git


The following commit(s) were added to refs/heads/master by this push:
     new 00336ad  Small changes on "DAGs and Tasks documentation" (#14853)
00336ad is described below

commit 00336ad820189adeca96b55c92f33a75877860cb
Author: JavierLopezT <ja...@gmail.com>
AuthorDate: Sun May 9 23:11:34 2021 +0200

    Small changes on "DAGs and Tasks documentation" (#14853)
---
 airflow/example_dags/tutorial.py     |   9 ++++++---
 docs/apache-airflow/img/dag_doc.png  | Bin 0 -> 40094 bytes
 docs/apache-airflow/img/task_doc.png | Bin 0 -> 245714 bytes
 docs/apache-airflow/tutorial.rst     |   7 ++++++-
 4 files changed, 12 insertions(+), 4 deletions(-)

diff --git a/airflow/example_dags/tutorial.py b/airflow/example_dags/tutorial.py
index 09d6ca3..6d0b522 100644
--- a/airflow/example_dags/tutorial.py
+++ b/airflow/example_dags/tutorial.py
@@ -89,18 +89,21 @@ with DAG(
     # [END basic_task]
 
     # [START documentation]
-    dag.doc_md = __doc__
-
     t1.doc_md = dedent(
         """\
     #### Task Documentation
     You can document your task using the attributes `doc_md` (markdown),
     `doc` (plain text), `doc_rst`, `doc_json`, `doc_yaml` which gets
     rendered in the UI's Task Instance Details page.
-
     ![img](http://montcs.bloomu.edu/~bobmon/Semesters/2012-01/491/import%20soul.png)
+
     """
     )
+
+    dag.doc_md = __doc__  # providing that you have a docstring at the beggining of the DAG
+    dag.doc_md = """
+    This is a documentation placed anywhere
+    """  # otherwise, type it like this
     # [END documentation]
 
     # [START jinja_template]
diff --git a/docs/apache-airflow/img/dag_doc.png b/docs/apache-airflow/img/dag_doc.png
new file mode 100644
index 0000000..22bc78c
Binary files /dev/null and b/docs/apache-airflow/img/dag_doc.png differ
diff --git a/docs/apache-airflow/img/task_doc.png b/docs/apache-airflow/img/task_doc.png
new file mode 100644
index 0000000..f31c99a
Binary files /dev/null and b/docs/apache-airflow/img/task_doc.png differ
diff --git a/docs/apache-airflow/tutorial.rst b/docs/apache-airflow/tutorial.rst
index b7db57a..b06288f 100644
--- a/docs/apache-airflow/tutorial.rst
+++ b/docs/apache-airflow/tutorial.rst
@@ -184,7 +184,9 @@ Adding DAG and Tasks documentation
 ----------------------------------
 We can add documentation for DAG or each single task. DAG documentation only support
 markdown so far and task documentation support plain text, markdown, reStructuredText,
-json, yaml.
+json, yaml. The DAG documentation can be written as a doc string at the beginning of the DAG file (recommended)
+or anywhere in the file. Below you can find some examples on how to implement task and DAG docs,
+as well as screenshots:
 
 .. exampleinclude:: /../../airflow/example_dags/tutorial.py
     :language: python
@@ -192,6 +194,9 @@ json, yaml.
     :start-after: [START documentation]
     :end-before: [END documentation]
 
+.. image:: img/task_doc.png
+.. image:: img/dag_doc.png
+
 Setting up Dependencies
 -----------------------
 We have tasks ``t1``, ``t2`` and ``t3`` that do not depend on each other. Here's a few ways