3

我在用于配置 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.
4

1 回答 1

3

选项定义和描述是如何定义的

“秘密”是：

  • 选项定义从任何行开始，以-or开头--（忽略空格）。
  • 选项定义和选项描述必须至少用两个空格分隔。
  • 一旦找到下一个选项定义，选项描述就结束。缩进不足的行或空行不会结束描述。
  • 作为选项描述的一部分的任何 [defaults: block] 都是有效的并被使用。

如何处理描述格式

很少有东西可以帮助使用更长的选项描述或选项定义。

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

原始代码是如何重组的

这是您的示例中重新组织的文档字符串的示例。

做了什么：

  • 选项描述文本从第 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
于 2015-08-14T13:30:30.707 回答