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

我写了一个小命令行工具，并且希望将“--help”用法消息添加到文档。将命令行工具的使用帮助添加到README.rst

由于我很懒，我想尽可能简化更新过程。这里是我想要更新工作流程的样子：

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

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

第一步来自我自己的大脑。但是想重复使用现有的Step2工具。

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

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

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

这里是我对工作的工具：https://github.com/guettli/reprec

来源

2016-11-29 guettli

我不知道我的理解正确：与'--help'输出选项生成'README.rst'编程方式从其他手动编辑的文件一起？ – bli

我不确定“如何”，但我知道结果应该是什么样子。我希望'myprod --help'的输出在README中可见。自动更新自述文件将是一个解决方案。做某种包括将是首选，因为我不希望在git中自动创建文本。我被告知所有创建的东西（比如来自编译器的二进制文件）不应该在git中。 – guettli

也许你应该在你的问题中加入这些信息。尽管关于git的一般建议，我会自动从两个文件（帮助后的文本和文本之后的文本）和'myprod --help'的输出或一些其他等效设置（自动替换）重新创建自述文件，并将其与'myprod'的更新一起提交。你可能会在git下有这个README文件，所以我猜这个“不跟踪自动生成文件的变化”的建议在这里并不重要。 – bli

正如评论中所建议的那样，您可以使用git pre-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的实现，但我没有测试它。

来源

2016-12-08 09:52:26 daphtdazz

为获得使用文本在步骤2，则可以使用subprocess

来源

2016-12-02 10:12:15 otorrillas

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

来源

2016-12-07 10:28:38 pradyunsg

工具'cog'看起来像一个简单的模板语言（如jinia）。尼斯。如果我将[[[cog ...]]]放入README.rst文件，github是否会渲染cog？ – guettli

Cog不是模板语言。从http://nedbatchelder.com/code/cog/开始，“Cog以一种非常简单的方式转换文件：它发现嵌入在其中的Python代码块，执行Python代码并将其输出插回到原始文件中。文件可以包含任何你喜欢Python代码的文本，它通常是源代码。“ - 请关于链接页面。 – pradyunsg

回到你的问题，Github没有渲染齿轮，答案显示了你可以改变帮助部分以使用齿轮。 – pradyunsg

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

我个人认为，简单的代码在your argument parsing function，而且可能更安全，因为当你宣布他们argparse可以验证很多条件上给出的参数，只要（如数据类型，参数的数目等）
，您可以使用argparse功能的参数直接在代码文件中，就在你声明它们（如：help，usage，epilog等）;这实际上意味着你可以完全删除your own usage function，因为argparse会为你处理这个任务（只需运行--help即可查看结果）。

总之，基本上，参数，它们的合同和帮助文档大部分是声明性的，并且只在一个地方完全管理。

好的，好的，我知道，这个问题最初代表了如何更新自述文件。我明白你的意图是采取最懒惰的方法。所以，我认为，这是懒惰不够：

在一个地方维护所有参数和它们的文档，一旦如上
然后运行像myprograom --help > README.rst
承诺;）

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

有README.template.rst（你实际上保持自述内容），并与## Usage头在某处：

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

，你会得到一切从同一源代码工作！

我认为它仍然需要一些抛光，以生成有效的rst文件，但我希望它通常显示的想法。

要点：Include generated help into README

来源

2016-12-08 23:17:07 Timur

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

回答

相关问题