ホーム>プログラミング関連>パイソン
ダウンロード

グリップ -- GitHub Readme インスタント プレビュー

GitHub に送信する前に、ローカルの Readme ファイルをレンダリングします。

Grip は、Python で書かれたコマンドライン サーバー アプリケーションで、GitHub マークダウン API を使用してローカルの Readme ファイルをレンダリングします。スタイルとレンダリングは GitHub から直接取得されるため、どのように表示されるかが正確にわかります。 Readme に加えた変更は、ページを更新しなくても、すぐにブラウザに反映されます。

モチベーション

GitHub にコミットしてプッシュする前に、正確な readme 結果を確認したい場合があります。

特に Readme 主導の開発を行う場合はそうです。

インストール

グリップを取り付けるには、次の手順を実行します。 

$ pip install grip

OS X では、Homebrew を使用してインストールすることもできます。 

$ brew install grip

使用法

リポジトリの Readme を表示するには: 

$ 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/

あるいは、グリップは相対 URL をサポートしているため、 gripを実行して localhost:6419/AUTHORS.md にアクセスすることもできます。

前の例を組み合わせることができます。または、ポートの代わりにホスト名を指定します。または両方を提供します。 

$ 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

2 番目の引数で出力名を制御します。 

$ 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/

注: ^D Ctrl+Dを意味し、Linux および OS X で動作します。Windows ではCtrl+Zを使用する必要があります。

コメントや問題などのユーザー コンテンツとしてのレンダリングもサポートされており、問題にリンクするためのオプションのリポジトリ コンテキストが含まれます。 

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

詳細と追加オプションについては、ヘルプを参照してください。 

$ grip -h

アクセス

Grip は可能な限り GitHub に近づけるように努めています。これを実現するために、グリップは GitHub の Markdown API を使用して、レンダリング エンジンへの変更がすぐに反映されるようにし、グリップをアップグレードする必要はありません。ただし、このため、API の時間レート制限に達する可能性があります。この問題が発生した場合、グリップは認証情報を使用して API にアクセスし、より高いレート制限のロックを解除する方法を提供します。 

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

または、空のスコープを持つパーソナル アクセス トークンを使用します (GitHub アカウントが 2 要素認証で設定されている場合はトークンが必要であることに注意してください)。 

$ grip --pass < token >

これらのオプションをローカル構成に保持できます。セキュリティ上の理由から、パスワードではなくアクセス トークンを使用することを強くお勧めします。 (パスワード マネージャーからパスワードを取得するようにグリップを構成することで、パスワードを安全に保つこともできます。)

オフライン レンダリングを提供するための作業中のブランチもあります。これがより正確に GitHub に似るようになると、CLI で公開され、最終的には API にアクセスできない場合のシームレスなフォールバック エンジンとして使用されるようになります。

Grip は常に HTTPS 経由で GitHub にアクセスするため、README と認証情報は保護されます。

ヒント

コミュニティの他のユーザーがどのようにグリップを使用しているかを次に示します。

あなた自身のものを共有したいですか？ @joeyespo に挨拶するか、プル リクエストを送信してください。

Github Wiki のローカル ミラーを作成する

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

ジョシュア・グルノー著。

リンクされた README ファイルのコレクションから HTML ドキュメントを生成

  1. ディレクトリを入力してください: 

    $ cd YOUR_DIR
$ export GRIPURL= $( pwd )

  2. CACHE_DIRECTORY構成変数を設定して、すべてのアセットを含めます。

    > ~/.grip/settings.py">
    $ echo " CACHE_DIRECTORY = ' $( pwd ) /assets' " >> ~ /.grip/settings.py

  3. 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・タヌジャジャ著。

構成

グリップをカスタマイズするには、 ~/.grip/settings.pyを作成し、次の変数を 1 つ以上追加します。

  • 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 )

API

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にある Readme ファイルをレンダリングします。 

 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 : レンダリングするファイル名、または Readme ファイルを含むディレクトリ。デフォルトは現在の作業ディレクトリです。
  • host : 待機するホスト。デフォルトは HOST 構成変数です。
  • port : リッスンするポート。デフォルトは PORT 構成変数です。
  • user_content : ユーザーのコメントや問題などのユーザーコンテンツとしてドキュメントをレンダリングするかどうか
  • context : user_contentが true の場合に使用するプロジェクト コンテキスト。 username/projectの形式になります。
  • username : API 制限を拡張するために GitHub で認証するユーザー
  • password : API 制限を拡張するために GitHub で認証するためのパスワード
  • 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 : カスタム グリップ クラスを使用します

輸出

指定された Readme ファイルをスタイルとアセットをインライン化して 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 : レンダリングするファイル名、または Readme ファイルを含むディレクトリ。デフォルトは現在の作業ディレクトリです。
  • user_content : ユーザーのコメントや問題などのユーザーコンテンツとしてドキュメントをレンダリングするかどうか
  • context : user_contentが true の場合に使用するプロジェクト コンテキスト。 username/projectの形式になります。
  • username : API 制限を拡張するために GitHub で認証するユーザー
  • password : API 制限を拡張するために GitHub で認証するためのパスワード
  • 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 : マークダウン ファイルを表示するためのテーマ (ライト モードまたはダーク モード)。有効なオプション (「明るい」、「暗い」)。デフォルト:「ライト」。
  • grip_class : カスタム グリップ クラスを使用します

アプリの作成

Readme ファイルのレンダリングと提供に使用できる 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 : レンダリングするファイル名、または Readme ファイルを含むディレクトリ。デフォルトは現在の作業ディレクトリです。
  • user_content : ユーザーのコメントや問題などのユーザーコンテンツとしてドキュメントをレンダリングするかどうか
  • context : user_contentが true の場合に使用するプロジェクト コンテキスト。 username/projectの形式になります。
  • username : API 制限を拡張するために GitHub で認証するユーザー
  • password : API 制限を拡張するために GitHub で認証するためのパスワード
  • 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 : pathから読み込まれる代わりにレンダリングする Markdown テキストの文字列またはストリーム (注: pathページ タイトルの設定に使用できます)
  • grip_class : カスタム グリップ クラスを使用します

render_app

create_appによって作成されたアプリケーションをレンダリングし、そのルートにアクセスしたときに通常表示される HTML を返します。 

 render_app ( app , route = '/' )
  • app : レンダリングする Flask アプリケーション
  • route : レンダリングするルート、デフォルトでは '/'

レンダリングコンテンツ

指定されたマークダウン テキストをキャッシュせずにレンダリングします。 

 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 : API 制限を拡張するために GitHub で認証するユーザー
  • password : API 制限を拡張するために GitHub で認証するためのパスワード
  • render_offline : Python-Markdown を使用してローカルでレンダリングするかどうか (注: これは進行中の作業です)
  • api_url : Github API の別のベース URL (例: Github Enterprise インスタンスのベース URL)。これは、オフライン レンダラーを使用しない場合に必要です。
  • title : ページのタイトル。デフォルトではpathから取得されます。

render_page

指定されたパスまたはテキストからマークダウンをキャッシュせずにレンダリングし、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 : ページ タイトルに使用するパス。なしの場合は'README.md'をレンダリングします。
  • user_content : ユーザーのコメントや問題などのユーザーコンテンツとしてドキュメントをレンダリングするかどうか
  • context : user_contentが true の場合に使用するプロジェクト コンテキスト。 username/projectの形式になります。
  • username : API 制限を拡張するために GitHub で認証するユーザー
  • password : API 制限を拡張するために GitHub で認証するためのパスワード
  • 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 : pathから読み込まれる代わりにレンダリングする Markdown テキストの文字列またはストリーム (注: pathページ タイトルの設定に使用できます)
  • quiet : 端末に出力しません
  • theme : マークダウン ファイルを表示するためのテーマ (ライト モードまたはダーク モード)。有効なオプション (「明るい」、「暗い」)。デフォルト:「ライト」。
  • grip_class : カスタム グリップ クラスを使用します

キャッシュのクリア

キャッシュされたスタイルとアセットをクリアします。 

 clear_cache ( grip_class = None )

主要

指定された引数を使用してグリップを実行します。 

 main ( argv = None , force_utf8 = True )
  • argv : 実行する引数、デフォルトではsys.argv[1:]
  • force_utf8 : 現在の Python インスタンスのデフォルトのエンコーディングをutf-8に設定します。 Unicode はデフォルトで処理されるため、これは Python 3 には影響しません。

クラス

クラスグリップ(フラスコ)

README を含むファイルまたはディレクトリを提供できる Flask アプリケーション。 

 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 ()
add_content_types

application/x-font-woff および application/octet-stream コンテンツ タイプが存在しない場合は追加します。初期化時に追加のコンテンツ タイプを追加するようにオーバーライドします。 

 Grip . add_content_types ()
キャッシュのクリア

ダウンロードしたアセットをクリアします。 

 Grip . clear_cache ()
与える

アプリケーションをレンダリングし、ブラウザにアクセスしたときに通常表示される HTML Unicode を返します。 

 Grip . render ( route = None )
  • route : レンダリングするルート、 /デフォルト
走る

サーバーを起動して README を表示します。これは内部的に Flask.run を呼び出します。 

 Grip . run ( host = None , port = None , debug = None , use_reloader = None , open_browser = False )
  • host : リッスンするホスト名。サーバーを外部からも利用できるようにするには、これを'0.0.0.0'に設定します。デフォルトでは'localhost'です。
  • port : Webサーバーのポート。デフォルトは6419
  • debug : 指定した場合、デバッグ モードを有効または無効にします。 Flask.debug を参照してください。
  • use_reloader : モジュールが変更された場合、サーバーは自動的に Python プロセスを再起動する必要がありますか? DEBUG_GRIP設定が指定されていない限り、デフォルトではFalse 。
  • open_browser : サーバーの起動時にブラウザをアドレスで開きます。

クラス AlreadyRunningError(RuntimeError)

サーバーがすでに実行されているときにGrip.runが呼び出されるときに発生します。 

 AlreadyRunningError ()

クラス ReadmeNotFoundError(NotFoundError または IOError)

指定された Readme が見つからなかった場合に発生します。 

 ReadmeNotFoundError ( path = None , message = None )

クラスReadmeAssetManager(オブジェクト)

Readme ページでレンダリングされるスタイルおよびフォント アセットを管理します。これは抽象基本クラスです。 

 ReadmeAssetManager ( cache_path , style_urls = None )

クラス GitHubAssetManager(ReadmeAssetManager)

Readme ページでレンダリングされるスタイルおよびフォント アセットを管理します。キャッシュを無効にするには、cache_path を None に設定します。

クラス ReadmeReader(オブジェクト)

URL サブパスから Readme コンテンツを読み取ります。これは抽象基本クラスです。 

 ReadmeReader ()

クラス DirectoryReader(ReadmeReader)

URL サブパスから Readme ファイルを読み取ります。 

 DirectoryReader ( path = None , silent = False )

クラス TextReader(ReadmeReader)

提供された Unicode 文字列から Readme コンテンツを読み取ります。 

 TextReader ( text , display_filename = None )

クラス StdinReader(TextReader)

STDIN から Readme テキストを読み取ります。 

 StdinReader ( display_filename = None )

クラス ReadmeRenderer(オブジェクト)

Readme をレンダリングします。これは抽象基本クラスです。 

 ReadmeRenderer ( user_content = None , context = None )

クラス GitHubRenderer(ReadmeRenderer)

GitHub Markdown API を使用して、指定された Readme をレンダリングします。 

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

クラス OfflineRenderer(ReadmeRenderer)

純粋な Python を使用して、指定された Readme をローカルでレンダリングします。注: これは現在不完全な機能です。 

 OfflineRenderer ( user_content = None , context = None )

定数

SUPPORTED_TITLES

GitHub 上の一般的な Markdown ファイルのタイトル。 

 SUPPORTED_TITLES = [ 'README' , 'Home' ]
  • filename : 読み取る UTF-8 ファイル。

SUPPORTED_EXTENSIONS

GitHub によって定義されている、サポートされている拡張機能。 

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

DEFAULT_FILENAMES

この定数には、ファイルが指定されていない場合にグリップが検索する名前が含まれます。 

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

DEFAULT_FILENAME

この定数には、デフォルトの Readme ファイル名が含まれます。 

 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 "

貢献する

  1. 未解決の問題を確認するか、新しい問題を開いて、機能のアイデアや見つけたバグに関するディスカッションを開始してください
  2. リポジトリをフォークして変更を加える
  3. 新しいプルリクエストを開く

PR がしばらく待っている場合は、Twitter でお気軽にご連絡ください。

このソフトウェアを頻繁に使用しますか? ?

拡大する
追加情報
おすすめ
関連情報 すべて