[GitHub] [airflow] mik-laj commented on pull request #9070: Shorten command help and move long help to command description

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

mik-laj commented on pull request #9070:
URL: https://github.com/apache/airflow/pull/9070#issuecomment-636313866


   I think we should also improve the description of some arguments.
   
   For example:
   ```
   airflow dags show --help
   ```
   Before
   ```
   usage: airflow dags show [-h] [--imgcat] [-s SAVE] [-S SUBDIR] dag_id
   
   positional arguments:
     dag_id                The id of the dag
   
   optional arguments:
     -h, --help            show this help message and exit
     --imgcat              Displays graph using the imgcat tool.
   
                           For more information, see: https://www.iterm2.com/documentation-images.html
     -s SAVE, --save SAVE  Saves the result to the indicated file.
   
                           The file format is determined by the file extension. For more information about supported format, see: https://www.graphviz.org/doc/info/output.html
   
                           If you want to create a PNG file then you should execute the following command:
                           airflow dags show <DAG_ID> --save output.png
   
                           If you want to create a DOT file then you should execute the following command:
                           airflow dags show <DAG_ID> --save output.dot
     -S SUBDIR, --subdir SUBDIR
                           File location or directory from which to look for the dag. Defaults to '[AIRFLOW_HOME]/dags' where [AIRFLOW_HOME] is the value you set for 'AIRFLOW_HOME' config you set in 'airflow.cfg'
   ```
   My proposition:
   ```
   usage: airflow dags show [-h] [--imgcat] [-s SAVE] [-S SUBDIR] dag_id
   
   The --imgcat option only works in iTerm. 
   For more information, see: https://www.iterm2.com/documentation-images.html
   
   Saving the graph
   
   The file format is determined by the file extension. For more information about supported format, see: https://www.graphviz.org/doc/info/output.html
   
   If you want to create a PNG file then you should execute the following command:
   airflow dags show <DAG_ID> --save output.png
   
   If you want to create a DOT file then you should execute the following command:
   airflow dags show <DAG_ID> --save output.dot
   
   positional arguments:
     dag_id                The id of the dag
   
   optional arguments:
     -h, --help            show this help message and exit
     --imgcat              Displays graph using the imgcat tool.
     -s SAVE, --save SAVE  Saves the result to the indicated file.
     -S SUBDIR, --subdir SUBDIR
                           File location or directory from which to look for the dag. Defaults to '[AIRFLOW_HOME]/dags' where [AIRFLOW_HOME] is the value you set for 'AIRFLOW_HOME' config you set in 'airflow.cfg'
   ```
   


----------------------------------------------------------------
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.

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