2016-11-29 105 views
3

我寫了一個小命令行工具,並且希望將「--help」用法消息添加到文檔。將命令行工具的使用幫助添加到README.rst

由於我很懶,我想盡可能簡化更新過程。這裏是我想要更新工作流程的樣子:

  1. 更新導致更新使用消息的代碼。
  2. 運行更新文檔的腳本:新的用法消息應該在文檔中可見。

換句話說:我不想複製粘貼使用信息。

第一步來自我自己的大腦。但是想重複使用現有的Step2工具。

到目前爲止,docs只是一個簡單的README.rst文件。

我想堅持一個簡單的解決方案,其中的文檔可以通過github直接看到。到目前爲止,我不需要更復雜的解決方案(如readthedocs)。

如何避免複製粘貼--help用法消息?

這裏是我對工作的工具:https://github.com/guettli/reprec

+0

我不知道我的理解正確:與'--help'輸出選項生成'README.rst'編程方式從其他手動編輯的文件一起? – bli

+1

我不確定「如何」,但我知道結果應該是什麼樣子。我希望'myprod --help'的輸出在README中可見。自動更新自述文件將是一個解決方案。做某種包括將是首選,因爲我不希望在git中自動創建文本。我被告知所有創建的東西(比如來自編譯器的二進制文件)不應該在git中。 – guettli

+1

也許你應該在你的問題中加入這些信息。 儘管關於git的一般建議,我會自動從兩個文件(幫助後的文本和文本之後的文本)和'myprod --help'的輸出或一些其他等效設置(自動替換)重新創建自述文件,並將其與'myprod'的更新一起提交。你可能會在git下有這個README文件,所以我猜這個「不跟蹤自動生成文件的變化」的建議在這裏並不重要。 – bli

回答

3

正如評論中所建議的那樣,您可以使用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的實現,但我沒有測試它。

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]]] 
+0

工具'cog'看起來像一個簡單的模板語言(如jinia)。尼斯。如果我將[[[cog ...]]]放入README.rst文件,github是否會渲染cog? – guettli

+0

Cog不是模板語言。從http://nedbatchelder.com/code/cog/開始,「Cog以一種非常簡單的方式轉換文件:它發現嵌入在其中的Python代碼塊,執行Python代碼並將其輸出插回到原始文件中。文件可以包含任何你喜歡Python代碼的文本,它通常是源代碼。「 - 請關於鏈接頁面。 – pradyunsg

+0

回到你的問題,Github沒有渲染齒輪,答案顯示了你可以改變幫助部分以使用齒輪。 – pradyunsg

1

我實際上會以一種完全不同的方式,從另一方面。如果您改用argparse而不是現在使用的getopt,我認爲您描述的工作流可能會大大簡化。有了這個,你將有:

  • 我個人認爲,簡單的代碼在your argument parsing function,而且可能更安全,因爲當你宣佈他們argparse可以驗證很多條件上給出的參數,只要(如數據類型,參數的數目等)

  • ,您可以使用argparse功能的參數直接在代碼文件中,就在你聲明它們(如:helpusageepilog等);這實際上意味着你可以完全刪除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