技術標籤：開源專案

標準 Readme 生成工具 Python版

原倉庫 standard-readme
我的Python版倉庫 https://github.com/notfresh/md2

標準 Readme 樣式

README 檔案是人們通常最先看到的第一個東西。它應該告訴人們為什麼要使用、如何安裝、以及如何使用你的程式碼。README 檔案標準化能夠使得建立和維護 README 檔案更加簡單。畢竟，要寫好一個文件不是那麼容易的。

本倉庫包含以下內容：

1. 一個建立標準 README 的生成器的 Python 版本。
   (也許它現在還有很多問題,但是它有更多其他強大的功能正在開發中)

內容列表

• 背景
• 安裝
• 使用說明
• 徽章
• 示例
• 相關倉庫
• 維護者
• 如何貢獻
• 使用許可

背景

如果你的文件是完整的，那麼使用你程式碼的人就不用再去看程式碼了。這非常的重要。它使得你可以分離介面文件與具體實現。它意味著你可修改實現的程式碼而保持介面與文件不變。

請記住：是文件而非程式碼，定義了一個模組的功能。

—— Ken Williams, Perl Hackers

寫 README 從某種程度上來說相當不易，一直維護下去更是難能可貴。如果可以減少這個過程，則可以讓寫程式碼與修改程式碼更容易，使得是否在說明中指明一處需改有無必要更加清楚，你可以花費更少的時間來考慮是否你最初的文件是否需要更新，你可以分配更多的時間來寫程式碼而非維護文件。

同時，標準化在某些別的地方也有好處。有了標準化，使用者就可以花費更少的時間來搜尋他們需要的資訊，他們同時可以做一個工具來從描述中搜集資訊，自動跑示例程式碼，檢查授權協議等等。

這個倉庫的目標是：

1. 一個Python版本的 README 生成器用來快速搭建新的 README 的框架。

安裝

這個專案使用 Python3.

$ pip install md2-notfresh

為什麼叫 md2-notfresh 呢? 因為 notfresh 是我的 github ID,而 md 是 markdown 的縮寫,所以本來想用 md 作為命令的入口的, 但是因為 md = mkdir,被佔用了,所以我用 md2 來表示.

使用說明

這是一個 README 生成工具，你可以用它快速生成一個開原倉庫的README文件, 當然它本質上說是一個可自定義的 markdown 模板生成工具,更多功能正在開發中。

使用 md2 -h 來獲取幫助
使用 md2 readme 在當前目錄生成 README 檔案
使用 md2 update-url filename 來更新md檔案的網頁連結
使用 md2 update-space filename 來更新md檔案的英文字母和漢字的空格
# Prints out the standard-readme spec

我另外製作了兩個命令來做輔助工作, 他們分別是md2 update-url 和 md2 update-space , 我現在來簡單說一下他們的使用方法.

輔助命令用法

md2 update-url filename

如果我們平常喜歡使用 markdown 文件來進行寫作, 我想做討厭的之一是自己寫 [錨文字](實際url) 了,我們喜歡直接貼一個url, 但是這樣的壞處是, 如果這樣的 markdown 發表到部落格網站, 使用者是無法點選的, 只好http複製地址到位址列, 所以我就寫了這樣一個命令. 來自動檢測並幫助自動更新url
比如在 a.md 裡面的內容是

https://pypi.org/project/md2-notfresh/

使用命令 md2 update-url a.md 會把它的內容變成

[https://pypi.org/project/md2-notfresh/](https://pypi.org/project/md2-notfresh/)

如果 url 已經符合規範了, 那麼它就不會再次修改了. 所以多次操作是安全的. 它的原理是自動檢測 http:// 開頭的內容. 我們一般認為 http或者https 開頭的都是網址.

md2 update-space filename

如果我們平常喜歡使用 markdown 文件來進行寫作, 我想做討厭的之一中文和英文字元的空格, 比如Hello張三, 我們應該給張三和hello之間加上空格, 所以這個命令就是自動幫我們完成這件事的.

如果漢字和英文已經符合規範了, 那麼它就不會再次修改了. 所以多次操作是安全的.
這個命令請謹慎使用, 確保你真的想在中文和英文中間留一個空格.

徽章

如果你的專案遵循 Standard-Readme 而且專案位於 Github 上，非常希望你能把這個徽章加入你的專案。它可以更多的人訪問到這個專案，而且採納 Stand-README。 加入徽章並非強制的。

[外鏈圖片轉存失敗,源站可能有防盜鏈機制,建議將圖片儲存下來直接上傳(img-o1yeGevI-1610777883916)(https://img.shields.io/badge/readme%20style-standard-brightgreen.svg?style=flat-square)]

為了加入徽章到 Markdown 文本里面，可以使用以下程式碼：

[![standard-readme compliant](https://img.shields.io/badge/readme%20style-standard-brightgreen.svg?style=flat-square)](https://github.com/RichardLitt/standard-readme)

示例

想了解我們建議的規範是如何被應用的，請參考 example-readmes。

相關倉庫

• Art of Readme —