我写了一个小命令行工具,并想在文档中添加“--help”用法消息。
由于我很懒,我想让更新程序尽可能简单。以下是我想要的更新工作流程:
换句话说:我不想复制+粘贴使用信息。
Step1来自我自己的大脑。但是想要重用Step2的现有工具。
到目前为止,文档只是一个简单的README.rst文件。
我想坚持使用一个简单的解决方案,通过github可以直接看到文档。到目前为止,我不需要更复杂的解决方案(如readthedocs)。
如何避免复制+粘贴--help用法消息?
以下是我正在处理的工具:https://github.com/guettli/reprec
答案 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功能直接在代码中记录参数,就在你声明它们的地方(例如:help,usage,epilog和其他人);这实际上意味着您可以完全删除your own usage function,因为argparse会为您处理此任务(只需与--help
一起运行以查看结果)。
总而言之,论证,他们的合同和帮助文档基本上都是声明性的,并且只在一个地方完全管理。
好的,好的,我知道,最初的问题是如何更新README。我知道你的意图是采取最懒惰的方法。所以,我认为,这很懒惰:
myprograom --help > README.rst
好的,你可能需要比> 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
文档,仍然需要进行一些修改,但我希望它能够显示出一般的想法。