Как можно обернуть текст в настройках Docopt?

У меня есть несколько подробных спецификаций опций в строке документации, используемой для настройки Docopt. Некоторые из предметов довольно длинные. Есть ли способ обернуть текст, чтобы сделать его более разборчивым или чтобы его было легче разместить по ширине линии?

Допустим, соответствующий фрагмент текста в строке документации следующий:

Usage:
    program [options]

Options:
    -h, --help                      Show this help message.
    -c, --configuration=CONF        Configuration (file) [default: None]
    -f, --files=FILESLIST           Comma-delimited list of input data files [default: 169888_ttH_el.root]
    -v, --variables=VARIABLESLIST   Comma-delimited list of variables to plot [default: trk_pt]
    -t, --tree=TREE                 Tree in input data files [default: mini]
    -u, --username=USERNAME         Username
    -t, --topanalysis=DIRECTORY     Directory of TopRootCore or TopAnalysis [default: /home/user/Dropbox/TopAnalysis]
    -s, --superlongoption=TEST      This is a very long option that requires a bit of text to explain it. [default: 101001011011101010010100110101010]
    --version                       Show the version and exit.

Можно ли было обернуть текст в стиле, например, в следующем?

Usage:
    program [options]

Options:
    -h, --help                      Show this help message.
    -c, --configuration=CONF        Configuration (file) [default: None]
    -f, --files=FILESLIST           Comma-delimited list of input data files
                                    [default: 169888_ttH_el.root]
    -v, --variables=VARIABLESLIST   Comma-delimited list of variables to plot
                                    [default: trk_pt]
    -t, --tree=TREE                 Tree in input data files [default: mini]
    -u, --username=USERNAME         Username
    -t, --topanalysis=DIRECTORY     Directory of TopRootCore or TopAnalysis
                                    [default: /home/user/Dropbox/TopAnalysis]
    -s, --superlongoption=TEST      This is a very long option that requires a
                                    bit of text to explain it.
                                    [default: 101001011011101010010100110101010]
    --version                       Show the version and exit.
Источник

1 ответ

Решение

Как определяется определение и описание варианта

"Секреты":

  • определение опции начинается с любой строки, начиная с - или же -- (пропуски игнорируются).
  • Определение опции и описание опции должны быть разделены как минимум двумя пробелами.
  • описание опции заканчивается, как только найдено следующее определение опции. Подстрочные или пустые строки не заканчивают описание.
  • любой [defaults: block], являющийся частью описания опции, действителен и используется.

Как бороться с форматированием описания

Есть несколько вещей, которые помогают использовать более длинные описания опций или определения опций.

  • Описание опции может начинаться с любой строки после определения опции.
  • Описание варианта может быть завернуто.
    • Даже строки с отступом являются частью описания опции.
    • Чтобы текст был разборчивым, оставляйте описание опций с отступом в фиксированном столбце (например, 27 или 29 или другой столбец, который вы считаете практичным). Это рекомендация, а не правило)
    • [default: block] работает хорошо, если это считается частью описания опции. Даже тексты с отступом и пустые строки тоже допускаются. Просто поместите его в любом месте, прежде чем определить следующий вариант.
  • Текст Option: не имеет никакого реального значения (несмотря на то, что часто используется в уроках docopt). Опции распознаются как любая строка, начинающаяся с - или же -- (начальные пробелы игнорируются). Это позволяет разбить параметры на группы.
  • имейте в виду, что определение и описание опции должны быть разделены как минимум двумя пробелами.

Как был реорганизован оригинальный код

Вот пример реорганизованной строки документа из вашего примера.

Что было сделано:

  • текст описания опции начинается в столбце 27
  • если определение опции заканчивалось в столбце 25 или позже (не допускается 2 пробела до начала текста описания опции), текст описания опции был перемещен на следующую строку.
  • Опции организованы в логические группы (показать это можно)
  • Опционные группы получили некоторое описание.

Переписанный пример

Конечный код выглядит следующим образом:

"""
Usage:
    program [options]

General options:
  These things are rather general, so placed in this group of option.

    -h, --help            Show this help message.
    --version             Show the version and exit.
    -c, --configuration=CONF
                          Configuration (file) [default: None]

Directory and path related stuff:
  Whatever relates to file or directory, comes here.

    -f, --files=FILESLIST
                          Comma-delimited list of input data files
                          [default: 169888_ttH_el.root]
    -t, --tree=TREE       Tree in input data files [default: mini]
    -t, --topanalysis=DIRECTORY
                          Directory of TopRootCore or TopAnalysis
                          [default: /home/user/Dropbox/TopAnalysis]
Other things:
  Remaining options live here.

    -v, --variables=VARIABLESLIST
                          Comma-delimited list of variables to plot
                          [default: trk_pt]
    -u, --username=USERNAME
                          Username
    -s, --superlongoption=TEST
                          This is a very long option that requires a bit of text
                          to explain it.
                          [default: 101001011011101010010100110101010]
"""
if __name__ == "__main__":
    from docopt import docopt
    args = docopt(__doc__)
    print args
Источник
Другие вопросы по тегам