將命令行工具的使用幫助添加到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

回答

相關問題