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

时间:2016-11-29 06:59:55

标签: python restructuredtext read-the-docs

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

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

  1. 更新导致更新使用消息的代码。
  2. 运行更新文档的脚本:新用法消息应在文档中可见。
  3. 换句话说:我不想复制+粘贴使用信息。

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

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

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

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

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

4 个答案:

答案 0 :(得分:3)

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

答案 1 :(得分:3)

根据注释中的建议,您可以使用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实现,但我还没有测试过。

答案 2 :(得分:1)

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

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

答案 3 :(得分:1)

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

  • 我个人认为,your argument parsing function中的代码更简单,可能更安全,因为argparse可以验证给定参数的很多条件,只要你声明它们(比如数据类型,参数个数)等等。)

  • 你可以使用argparse功能直接在代码中记录参数,就在你声明它们的地方(例如:helpusageepilog和其他人);这实际上意味着您可以完全删除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