Python項目的自述文件擴展

Python打包工具期望我們的自述文件應該命名爲README或README.txt。但是如果我們遵循這個約定，GitHub將它作爲純文本顯示在項目頁面中，這並不美觀。（與名爲README.rst的漂亮HTML版本不同）Python項目的自述文件擴展

是否有任何技術使PyPI和GitHub都對README感到滿意。

來源

2010-12-08 Ramana

PyPI does not * expect文件被命名爲README或README.txt。我不知道你的意思是什麼Python打包工具，但我不知道需要這種命名，如果它確實可以很容易修復。 – 2011-04-24 08:00:25

Lennart，當我運行沒有自述文件的`setup.py sdist`時，它說`警告：sdist：沒有找到標準文件：應該有一個README，README.txt` ......但我想這只是抱怨我可以忽視？ – rescdsk 2011-07-26 19:45:55

@rescdsk：是的，你可以忽略它。 AFAIK沒有什麼使用它。實際上，這應該是作爲錯誤報告提交的。 – 2011-08-11 07:04:18

你可以使用一個git filter driver這將，在結賬時，把你的README.md（由GitHub的需要），併產生一個適當的README（由Python的需要，雖然Lennart Regebro的answer表明PyPI將不會不要求任何README文件）

所以，保持拋開事實的PyPI不需要README（以及警告，可以簡單地被忽略），這裏是你如何能（一般）生成使用Git預期的文件：

smudge clean process

然而，任何修改私人文件README將需要手工上報README.md文件（因爲降價語法至少它沒有腳本可以猜測你）

這就是爲什麼Noufal Ibrahim的answer（其我upvoted）可能會更適應，尤其是如果你有機會到符號鏈接（我仍然與Windows XP的工作，所以對我來說沒有運氣）：

有使README是一個符號鏈接README.rst，或者像Arto Bendiken評論：
=>具有README.rst是符號鏈接README。

Git將存儲符號鏈接（和not the file the symlink refers to），因此您可以在您的Git庫中同時使用README及其README.rst文件。

來源

2010-12-08 06:52:51 VonC

我能想到的原始方法是使一個符號鏈接README稱爲README.rst，並檢查他們都英寸

來源

2010-12-08 06:59:18

PyPI中沒有規定，即文件名爲自述或README.txt文件，所以只是把它README .rst。事實上，根據我所知，PyPI根本不會在你的包中看到（雖然我可能在那裏是錯誤的，我還沒有研究代碼或任何東西），最後結束的文本是參數long_description 。

然後在你的setup.py，你做這樣的事情：

setup(name='Your module name', 
     version="1.0", 
     description="Whatever, dude.", 
     long_description=open('docs/README.rst', 'rt').read() 
)

來源

2010-12-08 11:02:02

引述埃裏克·阿勞霍在Python bug about the distutils warning：

在包裝/ distutils2，推薦的方式如下所示（以setup.cfg）：
[metadata] 
description-file = README.whatever 
sdist將包含該文件。您也可以直接在setup.cfg中寫入描述，並將您的README文件包含在extra_files字段中。

因此，基本上，忽略distutils關於缺少README.txt的警告。另外，distutils2據說不會發出這個警告（我沒有測試過），所以你可以嘗試升級。

來源

2011-09-19 17:40:59 rescdsk

在較舊的（非distutils2）設置中，您可以明確地將README.rst添加到MANIFEST.in文件中。您仍然會看到關於缺少標準README {.txt}的警告，但是您的README.rst將包含在您的sdist tarball中，這意味着它將包含在從PIPY直接下載的最終用戶中。

查看http://docs.python.org/2/distutils/sourcedist.html#the-manifest-in-template瞭解更多詳情。

來源

2013-07-09 16:07:43

Python項目的自述文件擴展

回答

相關問題