GitHubじゃ!Pythonじゃ!

GitHubからPython関係の優良リポジトリを探したかったのじゃー、でも英語は出来ないから日本語で読むのじゃー、英語社会世知辛いのじゃー

joeyespo

grip – ReadmeのようなGitHub Markdownファイルをコミットする前にプレビュー

投稿日:2018年5月21日 更新日:

ReadmeのようなGitHub Markdownファイルをコミットする前にプレビューしてください。

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

 

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

GripはPythonで書かれたコマンドライン サーバーアプリケーションで、 GitHubマークダウンAPIを使用してローカルのreadmeファイルをレンダリングします。 スタイルはGitHubから直接得られるので、どのように表示されるかを正確に知ることができます。 Readmeの変更は、ページの更新を必要とせず即座にブラウザに反映されます。

モチベーション

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

特に、 Readme主導の開発を行う場合。

インストール

gripをインストールするには、単純に以下のようにします。

$ 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をサポートしているので、グリップを実行して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/

すべてのスタイルとアセットをインラインにして、サーバーをバイパスして1つの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

stdinstdoutからの読み書きもサポートされているので、他のプログラムで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はLinuxとOS Xで動作するCtrl+D ^D意味します.WindowsではCtrl+Zを使用する必要があります。

コメント問題のようなユーザコンテンツとしてのレンダリングもサポートされています。

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

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

$ grip -h

アクセス

Gripは可能な限りGitHubに近いように努めています。 これを達成するために、GripはGitHubのMarkdown APIを使用し 、レンダリングエンジンの変更を直ちに反映させ、グリップをアップグレードする必要はありません。 ただし、このため、APIの時間制限率に達することがあります。 このような状況が発生した場合、グリップはクレデンシャルを使用してAPIにアクセスする方法を提供し、さらに高いレート制限を解除します。

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

または、スコープが空いている個人アクセストークンを使用します(GitHubアカウントに2段階認証が設定されている場合は、トークンが必要です )。

$ grip --pass <token>

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

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

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

ヒント

コミュニティの他の人がどのようにGripを使用しているかを示します。

あなた自身を共有したいですか? hello @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 設定変数を設定して、すべてのアセットをインクルードします
    $ echo "CACHE_DIRECTORY = '$(pwd)/assets'" >> ~/.grip/settings.py
  3. グリップを使用してすべての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スクリプトがあります

Matthew R. Tanudjaja

構成

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

  • HOST :CLI引数として提供されない場合に使用するlocalhost 、デフォルトではlocalhost
  • PORT :CLI引数として提供されない場合に使用するポート。デフォルトでは6419
  • DEBUG :エラーが発生したときにFlaskのデバッガを使用するかどうか、デフォルトではFalse
  • DEBUG_GRIP :エラーが発生したときに拡張情報を表示し、デフォルトではFalse
  • API_URL :github APIのベースURL(Github Enterpriseインスタンスなど)。 デフォルトで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引数として提供されない場合に使用するパスワードまたは個人用アクセストークンここにパスワードを保存しないでください。アクセストークンを使用するか、パスワード管理者からパスワードを取得してください

これはPythonファイルであることに注意してください。 'X' is not definedエラー'X' is not definedわかっている場合は、引用符を見落としている可能性があります。 例えば:

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

環境変数

  • GRIPHOME :代替のsettings.py場所を指定する~/.gripデフォルト
  • GRIPURL :グリップサーバーの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

ドキュメンテーション

サーブ

ローカルサーバーを実行し、ブラウザにアクセスしたときにReadmeファイルを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 :レンダリングするファイル名、またはReadmeファイルを含むディレクトリ。デフォルトは現在の作業ディレクトリです。
  • host :リスンするホスト、HOST構成変数のデフォルト値
  • port :リッスンするport 。デフォルトはPORT構成変数です。
  • user_content :ドキュメントをユーザーのコメントや問題のようなユーザーコンテンツとしてレンダリングするかどうか
  • contextuser_contentがtrueの場合に使用するプロジェクトコンテキストuser_content username/project形式をとりusername/project
  • username :GitHubで認証してAPI制限を拡張するユーザー
  • password :GitHubで認証してAPIの制限を拡張するためのパスワード
  • render_offlinePython-Markdownを使用してローカルにレンダリングするかどうか(注:これは進行中の作業です)
  • render_wide :ワイドページをレンダリングするかどうか、デフォルトではFalse (これはrender_wideとともに使用されても効果がありません)
  • render_inline :HTMLファイル内のスタイルをインライン化するかどうか
  • api_url :Github Enterpriseのインスタンスなど、github APIの異なるベースURL。 デフォルトは公開API https://api.github.comです。
  • title :デフォルトでpathから派生したページタイトル
  • autorefresh :Readmeファイルが変更されたときにレンダリングされたコンテンツを自動的に更新します。デフォルトはTrueです。
  • browser :サーバーの起動後にブラウザでタブを開きます。デフォルトではFalseです。
  • grip_class :カスタムGripクラスを使用する

輸出する

指定した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, grip_class=None)
  • path :レンダリングするファイル名、またはReadmeファイルを含むディレクトリ。デフォルトは現在の作業ディレクトリです。
  • user_content :ドキュメントをユーザーのコメントや問題のようなユーザーコンテンツとしてレンダリングするかどうか
  • contextuser_contentがtrueの場合に使用するプロジェクトコンテキストuser_content username/project形式をとりusername/project
  • username :GitHubで認証してAPI制限を拡張するユーザー
  • password :GitHubで認証してAPIの制限を拡張するためのパスワード
  • render_offlinePython-Markdownを使用してローカルにレンダリングするかどうか(注:これは進行中の作業です)
  • render_wide :ワイドページをレンダリングするかどうか、デフォルトではFalse (これはrender_wideとともに使用されても効果がありません)
  • render_inline :HTMLファイル内のスタイルをインライン化するかどうか(注:他のAPI関数とは異なり、これはデフォルトでTrue
  • out_filename :書き込むファイル名、デフォルトでは<in_filename>.html
  • api_url :Github Enterpriseのインスタンスなど、github APIの異なるベースURL。 デフォルトは公開API https://api.github.comです。
  • title :デフォルトでpathから派生したページタイトル
  • quiet :端末に印刷しない
  • grip_class :カスタムGripクラスを使用する

create_app

Readmeファイルのレンダリングと提供に使用できるFlaskアプリケーションを作成します。 これは、キャッシュされたスタイルを利用可能な場合に使用して、 serveexportによって使用される同じアプリケーションで、キャッシュを初期化します。

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 :ドキュメントをユーザーのコメントや問題のようなユーザーコンテンツとしてレンダリングするかどうか
  • contextuser_contentがtrueの場合に使用するプロジェクトコンテキストuser_content username/project形式をとりusername/project
  • username :GitHubで認証してAPI制限を拡張するユーザー
  • password :GitHubで認証してAPIの制限を拡張するためのパスワード
  • render_offlinePython-Markdownを使用してローカルにレンダリングするかどうか(注:これは進行中の作業です)
  • render_wide :ワイドページをレンダリングするかどうか、デフォルトではFalse (これはrender_wideとともに使用されても効果がありません)
  • render_inline :HTMLファイル内のスタイルをインライン化するかどうか
  • api_url :Github Enterpriseのインスタンスなど、github APIの異なるベースURL。 デフォルトは公開API https://api.github.comです。
  • title :デフォルトでpathから派生したページタイトル
  • textpathから読み込まれる代わりにレンダリングするMarkdownテキストの文字列またはストリーム(注: pathを使用してページタイトルを設定できます)
  • grip_class :カスタムGripクラスを使用する

render_app

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

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

render_content

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

render_content(text, user_content=False, context=None, username=None, password=None, render_offline=False, api_url=None, title=None)
  • text :レンダリングするMarkdownテキスト
  • user_content :ドキュメントをユーザーのコメントや問題のようなユーザーコンテンツとしてレンダリングするかどうか
  • contextuser_contentがtrueの場合に使用するプロジェクトコンテキストuser_content username/project形式をとりusername/project
  • username :GitHubで認証してAPI制限を拡張するユーザー
  • password :GitHubで認証してAPIの制限を拡張するためのパスワード
  • render_offlinePython-Markdownを使用してローカルにレンダリングするかどうか(注:これは進行中の作業です)
  • api_url :Github Enterpriseのインスタンスなど、github APIの異なるベースURL。 これは、オフラインレンダラを使用しない場合に必要です。
  • title :デフォルトでpathから派生したページタイトル

レンダリングページ

キャッシングせずに、指定されたパスまたはテキストからマークダウンをレンダリングし、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, grip_class=None)
  • path :ページタイトルに使用するpath'README.md'表示されます。
  • user_content :ドキュメントをユーザーのコメントや問題のようなユーザーコンテンツとしてレンダリングするかどうか
  • contextuser_contentがtrueの場合に使用するプロジェクトコンテキストuser_content username/project形式をとりusername/project
  • username :GitHubで認証してAPI制限を拡張するユーザー
  • password :GitHubで認証してAPIの制限を拡張するためのパスワード
  • render_offlinePython-Markdownを使用してオフラインでレンダリングするかどうか(注:これは進行中の作業です)
  • render_wide :ワイドページをレンダリングするかどうか、デフォルトではFalse (これはrender_wideとともに使用されても効果がありません)
  • render_inline :HTMLファイル内のスタイルをインライン化するかどうか
  • api_url :Github Enterpriseのインスタンスなど、github APIの異なるベースURL。 デフォルトは公開API https://api.github.comです。
  • title :デフォルトでpathから派生したページタイトル
  • textpathから読み込まれる代わりにレンダリングするMarkdownテキストの文字列またはストリーム(注: pathを使用してページタイトルを設定できます)
  • quiet :端末に印刷しない
  • grip_class :カスタムGripクラスを使用する

キャッシュの消去

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

clear_cache(grip_class=None)

メイン

Gripを指定された引数で実行します。

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, grip_url=None, static_url_path=None, instance_path=None, **kwargs)
default_renderer

現在の設定を使用してデフォルトのレンダラーを返します。 これは、レンダラーがコンストラクターで[なし]に設定されている場合にのみ使用されます。

Grip.default_renderer()
default_asset_manager

現在の設定を使用してデフォルトの資産マネージャを返します。 これは、コンストラクタで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ユニコードを返します。

Grip.render(route=None)
  • route :デフォルトでレンダリングする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が呼び出されたときに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)

提供されたユニコード文字列からReadmeコンテンツを読み込みます。

TextReader(text, display_filename=None)

クラスStdinReader(TextReader)

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

StdinReader(display_filename=None)

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

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

ReadmeRenderer(user_content=None, context=None)

クラスGitHubRenderer(ReadmeRenderer)

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

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

グリップサーバーとそのすべてのアセットのデフォルトURL:

DEFAULT_GRIPURL = '/__/grip'

DEFAULT_API_URL

デフォルトのapp_url値:

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

テスト

パッケージとテスト要件をインストールします。

$ pip install -e .[tests]

pytestでテストを実行する:

$ py.test

変更を加えたときにテストを再実行するには、 pytest-watchを使います:

$ ptw

外部仮定テスト

Gripに問題がある場合は、GitHub APIについての前提が壊れている可能性があります。 これを確認するには、以下を実行します。

$ py.test -m assumption

外部の前提はインターネット接続に依存しているため、ローカルで開発するときはスキップすることをお勧めします。 -xして最初の障害が発生したときに停止することで、サイクルをさらに強化します。

$ py.test -xm "not assumption"

またはpytest-watchで

$ ptw -- -xm "not assumption"







-joeyespo

執筆者: