如何定义选项定义和描述

Question

我在用于配置Docopt的docstring中有一些详细的选项规范。有些项目非常冗长。有没有办法包装文字，使其更容易辨认，或更容易使其适合线宽？

假设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

如何定义选项定义和描述

＆＃34;秘密＆＃34;是：

选项定义从任意行开始，从-或--开始（忽略空格）。
选项定义和选项说明必须至少由两个空格分隔。
选项说明在找到下一个选项定义后立即结束。缩进线或空白行不会结束描述。
作为选项说明一部分的任何[defaults：block]有效且已被使用。

如何处理描述格式

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

选项说明可以从选项定义后的任何行开始。
可能会包含选项说明。
- 即使是缩进行也是选项说明的一部分。
- 为了使文本清晰可见，请将选项说明缩进到固定列（例如27或29或其他您认为实用的列）。这是建议，而不是规则）
- [default：block]只要被视为选项说明的一部分，效果很好。即使是缩进的文本作品也允许使用空白行。在定义下一个选项之前，只需将它放在任何位置。
文字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

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

1 个答案:

如何定义选项定义和描述

如何处理描述格式

如何重新组织原始代码

重写示例