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

Question

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

因为我很懒，所以我希望更新过程尽可能简单。这是我希望更新工作流程的样子:

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

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

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

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

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

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

这是我正在使用的工具:https://github.com/guettli/reprec

Answer 1

正如评论中所建议的，您可以使用 git 预提交 Hook 在提交时生成 README.rst 文件。您可以使用现有的工具，例如 cog，或者您可以使用 bash 做一些非常简单的事情。

例如，创建一个RST"template"文件:

README.rst.tmpl

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

>>> INSERTION POINT FOR HELP OUTPUT <<<

.git/hooks/pre-commit

# 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 实现，但我还没有测试过它。