如何包装Docopt选项配置中的文本

Question

我在用于配置Docopt的docstring中有一些详细的选项规范。有些项目很长。有没有一种方法可以包装文本，使其更清晰或更容易地适应线宽？

假设文档字符串中的相关文本如下：

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.

Answer 1

如何定义选项定义和描述

"秘密"是：

• 选项定义从任意一行开始，从-或--开始（忽略空格）
• 选项定义和选项描述必须至少用两个空格分隔
• 找到下一个选项定义后，选项描述立即结束。缩进的行或空行不会结束描述
• 作为选项描述一部分的任何[默认值：块]都是有效的，并且会被使用

如何处理描述格式

有一些东西可以帮助使用较长的选项描述或选项定义。

• 选项描述可以从选项定义后的任意一行开始
• 选项描述可能被包装。
  • 即使是缩进的线条也是选项描述的一部分
  • 为了保持文本的易读性，请将选项描述缩进固定列（例如27或29或您认为实用的其他列）。这是建议，而不是规则）
  • 只要它被视为选项描述的一部分，[默认：块]就可以很好地工作。即使是缩进的文本作品和空行也是允许的。在定义下一个选项之前，只需将其放在任意位置即可
• 文本Option:没有实际意义（不管在docopt教程中经常使用）。选项被识别为以-或--开头的任何一行（忽略初始空格）。这允许将选项分组
• 请注意，选项定义和选项描述必须至少用两个空格分隔

原始代码是如何重组的

以下是您的示例中重新组织的doc字符串的示例。

做了什么：

• 选项说明文本从第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