コマンドラインツールの使い方をREADME.rstに追加する

Question

私は少しコマンドラインツールを書いて、 "--help"という使い方のメッセージをドキュメントに追加したいと思っています。

私は怠け者なので、できるだけ簡単に更新手順を作りたいと思います。更新ワークフローに次のようにしたいと思います：

1. 更新プログラムの使用状況メッセージが表示されます。
2. ドキュメントを更新するスクリプトを実行する：新しい使用法のメッセージがドキュメントに表示されるはずです。

他の言葉：私は使用法のメッセージをコピーして貼り付けたくありません。

Step1は私の脳のものです。しかし、Step2のために既存のツールを再利用したい。

これまでのドキュメントは、単なるREADME.rstファイルです。

私は単純な解決策を採用したいと思います。ドキュメントをgithubで直接見ることができます。これまでは、私はより複雑な解決策（readthedocsのような）は必要ありません。

--help使用法のメッセージをコピー＆ペーストするのを避けるにはどうすればよいですか？ここで

は、私が働いているツールです。https://github.com/guettli/reprec

Answer 1

コメントに示唆されているように、git pre-commitフックを使用してコミット時にREADME.rstファイルを生成することができます。あなたはコグなどの既存のツールを使うことができます。あるいは、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の実装が付属しているので、私はそれをテストしていません。

Answer 2

をステップ2で使用法テキストを取得するために、あなたはcogを使用することを検討してsubprocess

​​

Answer 3

を使用することができます。それはまさにこの仕事のためのものです。

---

これはちょうどうまくいくかもしれません。 （テストされていない）そして...改善の余地がたくさんある。

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 4

私は実際には別の側から全く異なる方法でアプローチします。あなたが今使っているgetoptの代わりにargparseに切り替えると、説明したワークフローが大幅に単純化されると思います。これであなたが持っているでしょう。おそらく

your argument parsing functionで

• 私は個人的に考えて、シンプルなコード、そしてより安全に、あなたがそれらを宣言するようargparseがいる限り、与えられた引数に条件の多くを検証することがあるので（データ型のように、引数の数など）

• と、あなたがそれら（例えば宣言する権利ところ、コード内で直接引数を文書化するargparseの機能を使用することができます。help、usage、epilogおよびその他）; argparseがあなたのためにこのタスクを処理するので（結果を見るにはちょうど--helpで実行されるので）、your own usage functionを完全に削除することができます。

基本的には、引数、その契約やヘルプドキュメントは、主に、宣言となり、総括、そして唯一の場所にまとめて管理します。

---

OK、OK、私が知っている、質問はもともと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ドキュメントを生成するためにはまだ研磨が必要だと思いますが、一般的な考え方を示すことを願っています。

要旨：私は私が正しく理解わからないInclude generated help into README