Allow for multi-line documentation of the function

[gregtatum]

I would like to provide longer documentation for my scripts, as they can be quite complicated. It would be nice to write full paragraphs and give example usage. Currently the main help has all of the newlines and whitespace stripped from the comments. This makes it hard to write a few paragraphs and give longer examples similar to the tldr project.

Maybe this could be a configuration option of some kind.

class Arguments(Tap):
    """
    Train a transformer model for translations.

    - Train a language on the full corpus:
      poetry run src/transformer_trainer.py -- --source "en" --target "es"

    - Test the system on a small subset of the corpus:
      poetry run src/transformer_trainer.py -- --source "en" --target "es" --small
    """

    source: str  # The source language, e.g. "en"
    target: str  # The target language, e.g. "es"
    small: bool = False  # Use a small test data set which is faster to load

poetry run src/transformer_trainer.py --help

Expected results:

➤ poetry run src/transformer_trainer.py --help
usage: transformer_trainer.py --source SOURCE --target TARGET [--small] [-h]

Train a transformer model for translations.

- Train a language on the full corpus:
  poetry run src/transformer_trainer.py -- --source "en" --target "es"

- Test the system on a small subset of the corpus:
  poetry run src/transformer_trainer.py -- --source "en" --target "es" --small

options:
  --source SOURCE  (str, required) The source language, e.g. "en"
  --target TARGET  (str, required) The target language, e.g. "es"
  --small          (bool, default=False) Use a small test data set which is faster to load
  -h, --help       show this help message and exit

Actual results:

➤ poetry run src/transformer_trainer.py --help
usage: transformer_trainer.py --source SOURCE --target TARGET [--small] [-h]

Train a transformer model for translations. - Train a language on the full corpus: poetry run
src/transformer_trainer.py -- --source "en" --target "es" - Test the system on a small subset of
the corpus: poetry run src/transformer_trainer.py -- --source "en" --target "es" --small

options:
  --source SOURCE  (str, required) The source language, e.g. "en"
  --target TARGET  (str, required) The target language, e.g. "es"
  --small          (bool, default=False) Use a small test data set which is faster to load
  -h, --help       show this help message and exit

[martinjm97]

Hi @gregtatum,

The current help string formatting matches the default behavior of argparse. You can achieve the desired behavior with:

"""main.py"""
from argparse import RawTextHelpFormatter
from tap import Tap

class Arguments(Tap):
    """
    Train a transformer model for translations.

    - Train a language on the full corpus:
      poetry run src/transformer_trainer.py -- --source "en" --target "es"

    - Test the system on a small subset of the corpus:
      poetry run src/transformer_trainer.py -- --source "en" --target "es" --small
    """

    source: str  # The source language, e.g. "en"
    target: str  # The target language, e.g. "es"
    small: bool = False  # Use a small test data set which is faster to load

args = Arguments(formatter_class=RawTextHelpFormatter).parse_args()

The output after calling python main.py -h is:

usage: python main.py [--small] --source SOURCE --target TARGET [-h]

    Train a transformer model for translations.

    - Train a language on the full corpus:
      poetry run src/transformer_trainer.py -- --source "en" --target "es"

    - Test the system on a small subset of the corpus:
      poetry run src/transformer_trainer.py -- --source "en" --target "es" --small

options:
  --small          (bool, default=False) 
  --source SOURCE  (str, required) 
  --target TARGET  (str, required) 
  -h, --help       show this help message and exit

Happy tapping, JK