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

Question

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

因为我比较懒，希望更新过程尽量简单。这是我希望更新工作流程的样子：

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

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

Step1来自我自己的大脑。但是想为步骤 2 重用现有工具。

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

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

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

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

Answer 1

要在 步骤 2 获取用法文本，您可以使用 subprocess

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

Answer 2

考虑使用 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 3

如评论中所建议，您可以使用 git 预提交挂钩在提交时生成 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 实现，但我还没有测试过了。

Answer 4

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

我个人认为，your argument parsing function中的代码更简单，而且可能更安全，因为 argparse 可能会验证给定参数的很多条件，只要你声明它们（比如数据类型, 参数数量等)
并且您可以使用 argparse 功能直接在代码中记录参数，就在您声明它们的地方（例如：help, usage, epilog and others); this effectively means that you could completely delete your own usage function，因为 argparse 将为您处理此任务（只是运行与 --help 查看结果）。

总而言之，论点、合同和帮助文档基本上都是声明性的，并且只在一个地方进行管理。

OK，OK，我知道了，原来的问题是如何更新README。我知道你的意图是采取最懒惰的方法。所以，我认为，它足够懒惰：

像上面一样在一个地方维护所有参数及其文档
然后运行类似 myprograom --help > README.rst
提交 ;)

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

具有 README.template.rst（您实际维护 README 内容的位置）并且其中有 ## Usage header：

$ 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

Add usage help of command line tool to README.rst

python

restructuredtext

read-the-docs