抓地力下載 - 抓地力原始碼下載

Grip－GitHub 自述文件即時預覽

在傳送到 GitHub 之前呈現本地自述文件。

Grip 是一個用 Python 編寫的命令列伺服器應用程序，它使用 GitHub markdown API 來呈現本機自述文件。樣式和渲染直接來自 GitHub，因此您將確切地知道它將如何顯示。您對自述文件所做的變更將立即反映在瀏覽器中，無需刷新頁面。

動機

有時您只想在提交並推送到 GitHub 之前查看確切的自述文件結果。

特別是在進行自述文件驅動的開發時。

安裝

要安裝握把，只需：

$ pip install grip

在 OS X 上，您也可以使用 Homebrew 安裝：

$ brew install grip

用法

要呈現儲存庫的自述文件：

$ cd myrepo
$ grip
 * Running on http://localhost:6419/

現在開啟瀏覽器並造訪 http://localhost:6419。或使用-b運行，Grip 將為您開啟一個新的瀏覽器標籤。

您也可以指定連接埠：

$ grip 80
 * Running on http://localhost:80/

或一個顯式文件：

$ grip AUTHORS.md
 * Running on http://localhost:6419/

或者，您可以只執行grip並存取localhost:6419/AUTHORS.md，因為grip 支援相對URL。

您可以結合前面的範例。或指定主機名稱而不是連接埠。或兩者都提供。

$ grip AUTHORS.md 80
 * Running on http://localhost:80/

$ grip CHANGES.md 0.0.0.0
 * Running on http://0.0.0.0:6419/

$ grip . 0.0.0.0:80
 * Running on http://0.0.0.0:80/

您甚至可以繞過伺服器並匯出到單一 HTML 文件，並內聯所有樣式和資源：

$ grip --export
Exporting to README.html

使用第二個參數控制輸出名稱：

$ grip README.md --export index.html
Exporting to index.html

如果您要匯出一堆文件，可以使用--no-inline阻止樣式內聯以節省空間：

$ grip README.md --export --no-inline introduction.html
Exporting to introduction.html

也支援從stdin和stdout讀取和寫入，讓您將 Grip 與其他程式一起使用：

$ cat README.md | grip -
 * Running on http://localhost:6419/

$ grip AUTHORS.md --export - | bcat

$ cat README.md | grip --export - | less

這使您可以透過直接在終端中輸入 Markdown 來快速測試外觀：

$ grip -
Hello **world**!
^D
 * Running on http://localhost:6419/

注意Ctrl+Z ^D表示Ctrl+D ，適用於 Linux 和 OS X。

也支援呈現為使用者內容（例如評論和問題） ，並具有用於連結到問題的可選儲存庫上下文：

$ grip --user-content --context=joeyespo/grip
 * Running on http://localhost:6419/

有關更多詳細資訊和其他選項，請參閱協助：

$ grip -h

使用權

Grip 努力盡可能接近 GitHub。為了實現這一點，grip 使用 GitHub 的 Markdown API，以便立即反映其渲染引擎的更改，而無需您升級grip。但是，因此您可能會達到 API 的每小時速率限制。如果發生這種情況，grip 提供了一種使用您的憑證存取 API 的方法，以解鎖更高的速率限制。

$ grip --user < your-username > --pass < your-password >

或使用範圍為空的個人存取權杖（請注意，如果您的 GitHub 帳戶設定了雙重認證，則需要令牌）：

$ grip --pass < token >

您可以將這些選項保留在本機配置中。出於安全目的，強烈建議您使用存取令牌而不是密碼。（您也可以透過設定 Grip 從密碼管理器取得密碼來確保密碼安全。）

還有一個正在進行中的分支來提供離線渲染。一旦它更準確地類似於 GitHub，它將在 CLI 中公開，並最終將用作無法存取 API 時的無縫回退引擎。

Grip 始終透過 HTTPS 存取 GitHub，因此您的 README 和憑證受到保護。

尖端

以下是社區中其他人如何使用 Grip。

想分享自己的嗎？向 @joeyespo 打個招呼或提交拉取請求。

建立 Github Wiki 的本地鏡像

$ git clone https://github.com/YOUR_USERNAME/YOUR_REPOSITORY.wiki.git
$ cd YOUR_REPOSITORY.wiki
$ grip

作者：約書亞‧古爾諾

從連結的 README 文件集合產生 HTML 文檔

輸入目錄：

$ cd YOUR_DIR
$ export GRIPURL= $( pwd )

透過設定CACHE_DIRECTORY配置變數來包含所有資源：
> ~/.grip/settings.py">
```
$ echo " CACHE_DIRECTORY = ' $( pwd ) /assets' " >> ~ /.grip/settings.py
```

使用 Grip 匯出所有 Markdown 文件，並將絕對資源路徑替換為相對路徑：

$ for f in * .md ; do grip --export $f --no-inline ; done
$ for f in * .html ; do sed -i ' ' " s? $GRIPURL /??g " $f ; done

您可以選擇使用下列指令將 HTML 檔案集壓縮到docs.tgz ：

$ tar -czvf docs.tgz ` ls | grep [ . ]html$ ` assets

正在尋找跨平台解決方案？這是一個等效的 Python 腳本。

作者：馬修‧R‧塔努賈賈 (Matthew R. Tanudjaja)

配置

若要自訂 Grip，請建立~/.grip/settings.py ，然後新增下列一個或多個變數：

HOST ：未作為 CLI 參數提供時使用的主機，預設為localhost
PORT ：未作為 CLI 參數提供時使用的端口，預設為6419
DEBUG ：發生錯誤時是否使用Flask的偵錯器，預設為False
DEBUG_GRIP ：發生錯誤時列印擴充訊息，預設為False
API_URL ：github API 的基本 URL，例如 Github Enterprise 實例的基本 URL。預設https://api.github.com
CACHE_DIRECTORY ：相對於~/.grip目錄，用於放置快取資源（這透過以下過濾器運行： CACHE_DIRECTORY.format(version=__version__) ），預設為'cache-{version}'
AUTOREFRESH ：檔案變更時是否自動刷新Readme內容，預設True
QUIET ：不列印擴充訊息，預設為False
STYLE_URLS ：將會加入呈現頁面的其他 URL，預設為[]
USERNAME ：未作為 CLI 參數提供時所使用的用戶名，預設為None
PASSWORD ：未提供 CLI 參數時使用的密碼或個人存取權令牌（請不要在此處儲存您的密碼。相反，請使用存取權杖或放入此代碼從密碼管理器取得您的密碼），預設情況下None

請注意，這是一個 Python 檔案。如果您看到'X' is not defined錯誤，您可能忽略了一些引號。例如：

 USERNAME = 'your-username'
PASSWORD = 'your-personal-access-token'

環境變數

GRIPHOME ：指定替代的settings.py位置，預設為~/.grip
GRIPURL ：Grip 伺服器的 URL，預設為/__/grip

先進的

該檔案是一個普通的Python腳本，因此您可以添加更高級的配置。

例如，要從環境中讀取設定並在未設定時提供預設值：

 PORT = os . environ . get ( 'GRIP_PORT' , 8080 )

應用程式介面

您可以直接使用 Python 存取 API，在您自己的專案中使用它：

 from grip import serve

serve ( port = 8080 )
 * Running on http : // localhost : 8080 /

直接運行main：

 from grip import main

main ( argv = [ '-b' , '8080' ])
 * Running on http : // localhost : 8080 /

或存取底層 Flask 應用程式以獲得更大的靈活性：

 from grip import create_app

grip_app = create_app ( user_content = True )
# Use in your own app

文件

服務

執行本機伺服器並在瀏覽器中存取時呈現位於path的自述文件。

 serve ( path = None , host = None , port = None , user_content = False , context = None , username = None , password = None , render_offline = False , render_wide = False , render_inline = False , api_url = None , title = None , autorefresh = True , browser = False , grip_class = None )

path ：要渲染的檔案名，或包含自述檔案的目錄，預設為目前工作目錄
host ：要監聽的主機，預設為 HOST 設定變數
port ：要監聽的端口，預設為 PORT 配置變量
user_content ：是否將文件呈現為使用者內容，例如使用者評論或問題
context : user_content為 true 時所使用的項目上下文，格式為username/project
username ：透過 GitHub 進行身份驗證以擴展 API 限制的用戶
password ：透過 GitHub 進行身份驗證以擴展 API 限制的密碼
render_offline ：是否使用 Python-Markdown 本地渲染（注意：這是一項正在進行的工作）
render_wide : 是否渲染寬頁面，預設為False （與user_content一起使用時沒有效果）
render_inline ：是否在 HTML 檔案中內嵌樣式
api_url ：github API 的不同基本 URL，例如 Github Enterprise 實例的基本 URL。預設是公共 API https://api.github.com。
title ：頁面標題，預設從path派生
autorefresh ：當Readme檔案改變時自動更新渲染內容，預設為True
browser : 伺服器啟動後在瀏覽器中開啟一個選項卡，預設為False
grip_class ：使用自訂 Grip 類

出口

將指定的自述文件寫入 HTML 文件，並內聯樣式和資源。

 export ( path = None , user_content = False , context = None , username = None , password = None , render_offline = False , render_wide = False , render_inline = True , out_filename = None , api_url = None , title = None , quiet = None , theme = 'light' , grip_class = None )

path ：要渲染的檔案名，或包含自述檔案的目錄，預設為目前工作目錄
user_content ：是否將文件呈現為使用者內容，例如使用者評論或問題
context : user_content為 true 時所使用的項目上下文，格式為username/project
username ：透過 GitHub 進行身份驗證以擴展 API 限制的用戶
password ：透過 GitHub 進行身份驗證以擴展 API 限制的密碼
render_offline ：是否使用 Python-Markdown 本地渲染（注意：這是一項正在進行的工作）
render_wide : 是否渲染寬頁面，預設為False （與user_content一起使用時沒有效果）
render_inline ：是否在 HTML 檔案中內嵌樣式（注意：與其他 API 函數不同，預設為True ）
out_filename ：要寫入的檔案名，預設為.html
api_url ：github API 的不同基本 URL，例如 Github Enterprise 實例的基本 URL。預設是公共 API https://api.github.com。
title ：頁面標題，預設從path派生
quiet ：不列印到終端
theme ：查看 Markdown 文件的主題（淺色模式或深色模式）。有效選項（「亮」、「暗」）。預設值：“光”。
grip_class ：使用自訂 Grip 類

創建應用程式

建立一個 Flask 應用程序，可用於渲染和提供自述文件。這與serve和export使用的應用程式相同，並使用可用的快取樣式來初始化快取。

 create_app ( path = None , user_content = False , context = None , username = None , password = None , render_offline = False , render_wide = False , render_inline = False , api_url = None , title = None , text = None , grip_class = None )

path ：要渲染的檔案名，或包含自述檔案的目錄，預設為目前工作目錄
user_content ：是否將文件呈現為使用者內容，例如使用者評論或問題
context : user_content為 true 時所使用的項目上下文，格式為username/project
username ：透過 GitHub 進行身份驗證以擴展 API 限制的用戶
password ：透過 GitHub 進行身份驗證以擴展 API 限制的密碼
render_offline ：是否使用 Python-Markdown 本地渲染（注意：這是一項正在進行的工作）
render_wide : 是否渲染寬頁面，預設為False （與user_content一起使用時沒有效果）
render_inline ：是否在 HTML 檔案中內嵌樣式
api_url ：github API 的不同基本 URL，例如 Github Enterprise 實例的基本 URL。預設是公共 API https://api.github.com。
title ：頁面標題，預設從path派生
text ：要渲染的 Markdown 文字字串或流，而不是從path載入（注意： path可用於設定頁面標題）
grip_class ：使用自訂 Grip 類

渲染應用程式

呈現由create_app建立的應用程式並傳回存取該路由時通常出現的 HTML。

 render_app ( app , route = '/' )

app ：要渲染的 Flask 應用程式
route : 渲染的路由，預設為 '/'

渲染內容

渲染指定的 Markdown 文字而不進行快取。

 render_content ( text , user_content = False , context = None , username = None , password = None , render_offline = False , api_url = None , title = None )

text : 要渲染的 Markdown 文本
user_content ：是否將文件呈現為使用者內容，例如使用者評論或問題
context : user_content為 true 時所使用的項目上下文，格式為username/project
username ：透過 GitHub 進行身份驗證以擴展 API 限制的用戶
password ：透過 GitHub 進行身份驗證以擴展 API 限制的密碼
render_offline ：是否使用 Python-Markdown 本地渲染（注意：這是一項正在進行的工作）
api_url ：github API 的不同基本 URL，例如 Github Enterprise 實例的基本 URL。當不使用離線渲染器時這是必要的。
title ：頁面標題，預設從path派生

渲染頁面

從指定路徑或文字渲染 markdown，不進行緩存，並傳回類似 GitHub Readme 視圖的 HTML 頁面。

 render_page ( path = None , user_content = False , context = None , username = None , password = None , render_offline = False , render_wide = False , render_inline = False , api_url = None , title = None , text = None , quiet = None , theme = 'light' , grip_class = None )

path : 用於頁面標題的路徑，如果 None 則呈現'README.md'
user_content ：是否將文件呈現為使用者內容，例如使用者評論或問題
context : user_content為 true 時所使用的項目上下文，格式為username/project
username ：透過 GitHub 進行身份驗證以擴展 API 限制的用戶
password ：透過 GitHub 進行身份驗證以擴展 API 限制的密碼
render_offline ：是否使用 Python-Markdown 離線渲染（注意：這是一項正在進行的工作）
render_wide : 是否渲染寬頁面，預設為False （與user_content一起使用時沒有效果）
render_inline ：是否在 HTML 檔案中內嵌樣式
api_url ：github API 的不同基本 URL，例如 Github Enterprise 實例的基本 URL。預設是公共 API https://api.github.com。
title ：頁面標題，預設從path派生
text ：要渲染的 Markdown 文字字串或流，而不是從path載入（注意： path可用於設定頁面標題）
quiet ：不列印到終端
theme ：查看 Markdown 文件的主題（淺色模式或深色模式）。有效選項（「亮」、「暗」）。預設值：“光”。
grip_class ：使用自訂 Grip 類

清除快取

清除快取的樣式和資源。

 clear_cache ( grip_class = None )

主要的

使用指定參數執行 Grip。

 main ( argv = None , force_utf8 = True )

argv ：運行時使用的參數，預設為sys.argv[1:]
force_utf8 ：將目前Python實例中的預設編碼設定為utf-8 。這對 Python 3 沒有影響，因為預設會處理 Unicode

課程

握把類（燒瓶）

一個 Flask 應用程序，可以提供包含 README 的檔案或目錄。

 Grip ( source = None , auth = None , renderer = None , assets = None , render_wide = None , render_inline = None , title = None , autorefresh = None , quiet = None , theme = 'light' , grip_url = None , static_url_path = None , instance_path = None , ** kwargs )

預設渲染器

使用目前配置返回預設渲染器。僅當渲染器在建構函數中設定為 None 時才使用。

 Grip . default_renderer ()

預設資產管理器

使用目前配置返回預設資產管理器。僅當 asset_manager 在建構函式中設定為 None 時才使用。

 Grip . default_asset_manager ()

新增內容類型

新增 application/x-font-woff 和 application/octet-stream 內容類型（如果缺少）。覆蓋以在初始化時添加其他內容類型。

 Grip . add_content_types ()

清除快取

清除下載的資源。

 Grip . clear_cache ()

使成為

呈現應用程式並傳回瀏覽器中存取時通常出現的 HTML unicode。

 Grip . render ( route = None )

route : 渲染的路由， /默認

跑步

啟動伺服器來呈現自述文件。這會在內部呼叫 Flask.run。

 Grip . run ( host = None , port = None , debug = None , use_reloader = None , open_browser = False )

host ：要偵聽的主機名稱。將其設為'0.0.0.0'以使伺服器也可以在外部使用，預設為'localhost'
port ：網路伺服器的連接埠。預設為6419
debug ：如果給定，啟用或停用偵錯模式。請參閱 Flask.debug。
use_reloader ：如果模組發生更改，伺服器是否應該自動重新啟動 python 進程？除非指定了DEBUG_GRIP設置，否則預設為False 。
open_browser ：伺服器啟動時開啟瀏覽器到該位址

類別已經運行錯誤（運行時錯誤）

當伺服器已在運行時調用Grip.run時引發。

 AlreadyRunningError ()

類 ReadmeNotFoundError（NotFoundError 或 IOError）

當找不到指定的自述文件時引發。

 ReadmeNotFoundError ( path = None , message = None )

類別 ReadmeAssetManager(物件)

管理使用自述文件頁面呈現的樣式和字體資源。這是一個抽象基底類別。

 ReadmeAssetManager ( cache_path , style_urls = None )

類別 GitHubAssetManager(ReadmeAssetManager)

管理使用自述文件頁面呈現的樣式和字體資源。將cache_path 設定為None 以停用快取。

ReadmeReader 類別（物件）

從 URL 子路徑讀取自述文件內容。這是一個抽象基底類別。

 ReadmeReader ()

類別 DirectoryReader(ReadmeReader)

從 URL 子路徑讀取自述檔案。

 DirectoryReader ( path = None , silent = False )

類別 TextReader(ReadmeReader)

從提供的 unicode 字串中讀取自述文件內容。

 TextReader ( text , display_filename = None )

類別 StdinReader(TextReader)

從 STDIN 讀取自述文件文字。

 StdinReader ( display_filename = None )

類別 ReadmeRenderer（物件）

呈現自述文件。這是一個抽象基底類別。

 ReadmeRenderer ( user_content = None , context = None )

類別 GitHubRenderer(ReadmeRenderer)

使用 GitHub Markdown API 呈現指定的自述文件。

 GitHubRenderer ( user_content = None , context = None , api_url = None , raw = None )

類別 OfflineRenderer(ReadmeRenderer)

使用純 Python 在本機呈現指定的自述檔案。注意：目前這是一個不完整的功能。

 OfflineRenderer ( user_content = None , context = None )

常數

支援的_標題

GitHub 上常見的 Markdown 文件標題。

 SUPPORTED_TITLES = [ 'README' , 'Home' ]

filename ：要讀取的 UTF-8 檔案。

SUPPORTED_EXTENSIONS 個

支援的擴展，由 GitHub 定義。

 SUPPORTED_EXTENSIONS = [ '.md' , '.markdown' ]

DEFAULT_FILENAMES

此常數包含未提供檔案時 Grip 尋找的名稱。

 DEFAULT_FILENAMES = [ title + ext
                     for title in SUPPORTED_TITLES
                     for ext in SUPPORTED_EXTENSIONS ]

DEFAULT_FILENAME

此常數包含預設的自述文件名，即：

 DEFAULT_FILENAME = DEFAULT_FILENAMES [ 0 ]  # README.md

DEFAULT_GRIPHOME

如果未指定GRIPHOME環境變量，則此常數指向預設值。

 DEFAULT_GRIPHOME = '~/.grip'

DEFAULT_GRIPURL

Grip 伺服器及其所有資產的預設 URL：

 DEFAULT_GRIPURL = '/__/grip'

DEFAULT_API_URL

預設 app_url 值：

 DEFAULT_API_URL = 'https://api.github.com'

測試

安裝套件並測試要求：

$ pip install -e .[tests]

使用 pytest 運行測試：

$ pytest

或要在進行變更時重新執行測試，請使用 pytest-watch：

$ ptw

外部假設測試

如果您在使用 Grip 時遇到問題，很可能是關於 GitHub API 的假設已被打破。要驗證這一點，請運行：

$ pytest -m assumption

由於外部假設依賴互聯網連接，因此在本地開發時您可能需要跳過它們。透過使用-x在第一次失敗時停止來進一步收緊循環：

$ pytest -xm " not assumption "

或使用 pytest-watch：

$ ptw -- -xm " not assumption "

貢獻

檢查未解決的問題或開啟新問題以圍繞您的功能想法或您發現的錯誤開始討論
分叉存儲庫並進行更改
打開一個新的拉取請求

如果您的公關已經等待了一段時間，請隨時在 Twitter 上與我聯繫。

常使用這個軟體嗎？？

展開