Argparse usability issues
🚀 Feature
Improve the usability of the argparse functionality by allowing to use extensions of argparse.
Motivation
Currently in pytorch-lightning argparse is used as parser = ArgumentParser(parents=[parent_parser]) which prevents many behaviors that users might want. The most basic example, someone implements a trainer.py tool, thus writes:
from argparse import ArgumentParser
from pytorch_lightning import Trainer
parser = ArgumentParser(description='My cool tool that uses pytorch-lightning')
parser = Trainer.add_argparse_args(parser) 
parser.parse_args()
If you then run trainer.py --help the description of the parser is not shown. This is because the parser that add_argparse_args returns is not the one that the user created. It is a new one that just copied the defined arguments, the rest being lost. Another feature lost is specifying a formatter_class for example doing parser = ArgumentParser(formatter_class=argparse.ArgumentDefaultsHelpFormatter).
Another consequence of the way argparse is currently used is that it is not possible to use argparse-like parsers. The argparse module is rather limited, so it would be nice to be able to use extensions of argparse. More specifically, I would really like to use jsonargparse with pytorch-lightning. This would for example make it trivial to parse arguments from a json or yaml configuration file. When you have so many options that can be configured such as with the Trainer class, a config file is simply a must. Reinventing the wheel by adding config file support to pytorch-lightning would not make much sense. Much better to use an existing package that already provides this.
I tried changing the pytorch-lightning code from parser = ArgumentParser(parents=[parent_parser]) to parser = parent_parser and use a jsonargparse parser. Unfortunately it failed with an AttributeError: 'bool' object has no attribute 'lower'. Without looking at the source code I imagine that a bool argument support has been added since argparse does not support it. However, jsonargparse already supports defining arguments with type=bool.
Honestly I can't imagine any benefit or good reason for using argparse's parent option here. If there is, please comment.
Pitch
I propose the following:

Internally use jsonargparse including its bool support.
Add arguments directly to the parser provided to add_argparse_args if the provided parser is a jsonargparse parser.
To be backwards compatible, the add_argparse_args would return the parser and use the parent option if the provided parser is not a jsonargparse parser.
Change the documentation to recommend using jsonargparse and describing its support for config files.

To pitch further, I would be more than willing to implement and create a pull request for this. I am the developer of jsonargparse and continuously work on machine learning. Also I think pytorch-lightning is an awesome project and plan to use it a lot and hopefully contribute to it.