Question

我写了一个小命令行工具，并想在文档中添加“--help”用法消息。

由于我很懒，我想让更新程序尽可能简单。以下是我想要的更新工作流程：

更新导致更新使用消息的代码。
运行更新文档的脚本：新用法消息应在文档中可见。

换句话说：我不想复制+粘贴使用信息。

Step1来自我自己的大脑。但是想要重用Step2的现有工具。

到目前为止，文档只是一个简单的README.rst文件。

我想坚持使用一个简单的解决方案，通过github可以直接看到文档。到目前为止，我不需要更复杂的解决方案（如readthedocs）。

如何避免复制+粘贴--help用法消息？

以下是我正在处理的工具：https://github.com/guettli/reprec

Answer 1

考虑使用cog。这完全是为了这份工作。

这里的东西可能会起作用。（未经测试）并且......还有很大的改进空间。

reprec
======

The tool reprec replaces strings in text files:

..  [[[cog
..      import cog
..  
..      def indent(text, width=4):
..          return "\n".join((" "*width + line) for line in text.splitlines())
..  
..      text = subprocess.check_output("reprec --help", shell=True)
..      cog.out("""
..  
..          ::
..  
..             ==> reprec --help""",
..          dedent=True
..      )
..      cog.out(indent(text))
..  ]]]

::

    ===> reprec --help
    <all-help-text>
..  [[[end]]]

Answer 2

根据注释中的建议，您可以使用git pre-commit钩子在commit上生成README.rst文件。你可以使用现有的工具，比如cog，或者你可以用bash做一些非常简单的事情。

例如，创建一个RST“模板”文件：

<强> README.rst.tmpl

Test Git pre-commit hook project
--------------------------------

>>> INSERTION POINT FOR HELP OUTPUT <<<

<强>的.git /钩/预提交

# Sensible to set -e to ensure we exit if anything fails
set -e

# Get the output from your tool.
# Paths are relative to the root of the repo
output=$(tools/my-cmd-line-tool --help)

cat README.rst.tmpl |
while read line
do
  if [[ $line == ">>> INSERTION POINT FOR HELP OUTPUT <<<" ]]
  then
    echo "$output"
  else
    echo "$line"
  fi
done > README.rst
git add README.rst

如果您未在命令行上传递提交消息，则会在提示您输入提交消息之前运行此命令。因此，如果对README.rst.tmpl或工具的输出进行任何更改时进行提交，则README.rst将随之更新。

修改

我认为这也适用于Windows，或类似的东西，因为git在Windows上带有bash实现，但我还没有测试过。

Answer 3

要获取 第2步 的使用文字，您可以使用subprocess

usage_text = subprocess.check_output("reprec --help", shell=True)

Answer 4

我实际上会以另一种方式以完全不同的方式接近。我认为如果您切换到使用argparse而不是现在使用的getopt，可能会大大简化您描述的工作流程。有了这个，你将拥有：

我个人认为，your argument parsing function中的代码更简单，可能更安全，因为argparse可以验证给定参数的很多条件，只要你声明它们（比如数据类型，参数个数）等等。）
你可以使用argparse功能直接在代码中记录参数，就在你声明它们的地方（例如：help，usage，epilog和其他人）;这实际上意味着您可以完全删除your own usage function，因为argparse会为您处理此任务（只需与--help一起运行以查看结果）。

总而言之，论证，他们的合同和帮助文档基本上都是声明性的，并且只在一个地方完全管理。

好的，好的，我知道，最初的问题是如何更新README。我知道你的意图是采取最懒惰的方法。所以，我认为，这很懒惰：

将您的所有参数及其文档保存在上面的单个位置
然后运行类似myprograom --help > README.rst
commit;）

好的，你可能需要比> README.rst更复杂的东西。在那里，我们可以随心所欲地创造，所以乐趣从这里开始。例如：

拥有README.template.rst（您实际维护README内容的地方）并在其中的某处包含## Usage标题：

$ myprogram --help > USAGE.rst
$ sed -e '/## Usage/r USAGE.rst' -e '$G' README.template.rst > README.rst

您可以使用相同的源代码来完成所有工作！

我认为为了生成有效的rst文档，仍然需要进行一些修改，但我希望它能够显示出一般的想法。

要点：Include generated help into README

将命令行工具的使用帮助添加到README.rst

4 个答案: