如何使用Sphinx為1文件python項目（腳本，無模塊）生成文檔？

Question

我有一個存儲在一個文件中的python項目，它是一個命令行工具。

我已經設法生成了所有就緒的sphinx文檔，但是如何確定我的文件是腳本而不是模塊？

Answer 1

使用Python編寫的命令行工具文檔記錄有多個選項：

• 命令直接顯示的幫助字符串
• README.rst用reStructuredText編寫，並通過rst2html轉換為html
• Sphinx文檔

（我不聲明，此列表是完整的）

從命令行打印幫助字符串

到目前為止，這是最易於訪問的文檔形式，因為安裝該程序的每個人都可以顯示它。

我強烈建議您使用docopt來解析命令行，因為它帶給您所有docopt -在源代碼中具有docstring（作為模塊docstring），並同時在命令行中具有docstring。

您可以在SO https://stackoverflow.com/a/23304876/346478中看到我的帖子，或者在這里您可以看到項目本身的示例：

"""Usage:
quick_example.py tcp <host> <port> [--timeout=<seconds>]
quick_example.py serial <port> [--baud=9600] [--timeout=<seconds>]
quick_example.py -h | --help | --version

"""
from docopt import docopt


if __name__ == '__main__':
    arguments = docopt(__doc__, version='0.1.1rc')
    print(arguments)

從命令行運行時：

$ python quick_example.py -h
Usage:
  quick_example.py tcp <host> <port> [--timeout=<seconds>]
  quick_example.py serial <port> [--baud=9600] [--timeout=<seconds>]
  quick_example.py -h | --help | --version

還有其他參數解析器，例如plac或argparse 。 我個人最喜歡docopt 。

README.rst用reStructuredText編寫，並通過rst2html轉換為html

編寫README.rst非常容易，並且具有優勢，即在github和bitbucket上，您的項目會自動閱讀，從而獲得了很好的可讀性介紹。

它也比Sphinx項目簡單得多，您不必使用多個文件，只需一個文件。

安裝docutils時：

$ pip install docutils

您將獲得一堆命令，這些命令可讓您將README.rst轉換為不錯的命令。 我從該集合中使用的唯一命令是rst2html （在Windows上為rst2html.py ，您必須rst2html.py使它工作，但絕對值得）。

為您的README.rst創建html：

$ rst2html README.rst README.html

我從vim編輯器執行此操作，它變得更加簡單:!rst2html % %.html生成README.rst.html文件的內容。

Sphinx文檔

我認為Sphinx是reStructuredText的擴展，並撰寫了幾本技術手冊-它提供了很好的交叉引用語法，我喜歡它。

但是對於命令行工具，我會認為它是過大的。

有關如何使用Sphinx的描述，請參閱其出色的文檔。

結論

Sphinx很棒，但是對於命令行工具來說似乎有些過頭了。

無論大小如何，reStructuredText README.rst都是任何Python項目的必不可少的部分，當您忘記了有關該項目的所有內容時，請將您認為方便的所有內容放在此處。

另一方面，我以html的形式向用戶提供了一組頁面，但我不確定他們真正閱讀該頁面的頻率。 人們很懶。

命令行上有關幫助選項的文檔似乎對我來說效果最好。 目前，您需要幫助（在命令行上鍵入），就可以在其中獲得幫助。 借助docopt之類的docopt它可以與源代碼中的docstring完美地內聯。

而且，如果您想對用戶進行投資，請用很少的熱鍵來教他們less （或more ）的命令來搜索/查找字符串，跳至下一個出現n ，返回一個出現N ，到達頂部gg或底部G h或H是您的朋友，請q安全中斷。

享受生活在命令行上。