grip Download - grip Unduh kode sumber

Grip -- Pratinjau Instan GitHub Readme

Render file readme lokal sebelum dikirim ke GitHub.

Grip adalah aplikasi server baris perintah yang ditulis dengan Python yang menggunakan API penurunan harga GitHub untuk merender file readme lokal. Gaya dan renderingnya datang langsung dari GitHub, jadi Anda akan tahu persis bagaimana tampilannya. Perubahan yang Anda buat pada Readme akan langsung terlihat di browser tanpa memerlukan penyegaran halaman.

Motivasi

Terkadang Anda hanya ingin melihat hasil readme yang sebenarnya sebelum melakukan dan mendorong ke GitHub.

Terutama ketika melakukan pengembangan berbasis Readme.

Instalasi

Untuk memasang pegangan, cukup:

$ pip install grip

Di OS X, Anda juga dapat menginstal dengan Homebrew:

$ brew install grip

Penggunaan

Untuk merender readme repositori:

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

Sekarang buka browser dan kunjungi http://localhost:6419. Atau jalankan dengan -b dan Grip akan membuka tab browser baru untuk Anda.

Anda juga dapat menentukan port:

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

Atau file eksplisit:

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

Alternatifnya, Anda bisa menjalankan grip dan mengunjungi localhost:6419/AUTHORS.md karena grip mendukung URL relatif.

Anda dapat menggabungkan contoh-contoh sebelumnya. Atau tentukan nama host, bukan port. Atau berikan keduanya.

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

Anda bahkan dapat melewati server dan mengekspor ke satu file HTML, dengan semua gaya dan aset disertakan:

$ grip --export
Exporting to README.html

Kontrol nama keluaran dengan argumen kedua:

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

Jika Anda mengekspor banyak file, Anda dapat mencegah gaya disisipkan untuk menghemat ruang dengan --no-inline :

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

Membaca dan menulis dari stdin dan stdout juga didukung, memungkinkan Anda menggunakan Grip dengan program lain:

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

$ grip AUTHORS.md --export - | bcat

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

Ini memungkinkan Anda dengan cepat menguji tampilannya dengan memasukkan Markdown langsung di terminal Anda:

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

Catatan: ^D artinya Ctrl+D , yang berfungsi di Linux dan OS X. Di Windows Anda harus menggunakan Ctrl+Z .

Merender sebagai konten pengguna seperti komentar dan masalah juga didukung, dengan konteks repositori opsional untuk menghubungkan ke masalah:

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

Untuk detail lebih lanjut dan opsi tambahan, lihat bantuan:

$ grip -h

Mengakses

Grip berusaha sedekat mungkin dengan GitHub. Untuk mencapai hal ini, grip menggunakan Markdown API GitHub sehingga perubahan pada mesin renderingnya segera terlihat tanpa mengharuskan Anda mengupgrade grip. Namun, karena hal ini, Anda mungkin mencapai batas tarif per jam API. Jika ini terjadi, grip menawarkan cara untuk mengakses API menggunakan kredensial Anda untuk membuka batas kecepatan yang jauh lebih tinggi.

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

Atau gunakan token akses pribadi dengan cakupan kosong (perhatikan bahwa token diperlukan jika akun GitHub Anda diatur dengan autentikasi dua faktor):

$ grip --pass < token >

Anda dapat mempertahankan opsi ini di konfigurasi lokal Anda. Untuk tujuan keamanan, sangat disarankan agar Anda menggunakan token akses melalui kata sandi . (Anda juga dapat menjaga keamanan kata sandi Anda dengan mengonfigurasi Grip untuk mengambil kata sandi Anda dari pengelola kata sandi.)

Ada juga cabang yang sedang dalam proses untuk menyediakan rendering offline . Jika ini lebih tepatnya menyerupai GitHub, maka ini akan diekspos di CLI, dan pada akhirnya akan digunakan sebagai mesin fallback yang mulus ketika API tidak dapat diakses.

Grip selalu mengakses GitHub melalui HTTPS, sehingga README dan kredensial Anda terlindungi.

Kiat

Berikut cara anggota komunitas lainnya menggunakan Grip.

Ingin berbagi milik Anda sendiri? Ucapkan halo @joeyespo atau kirimkan permintaan penarikan.

Buat cermin lokal dari Github Wiki

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

Oleh Joshua Gourneau.

Hasilkan dokumentasi HTML dari kumpulan file README yang tertaut

Masuk ke direktori:

$ cd YOUR_DIR
$ export GRIPURL= $( pwd )

Sertakan semua aset dengan mengatur variabel konfigurasi CACHE_DIRECTORY :
> ~/.grip/settings.py">
```
$ echo " CACHE_DIRECTORY = ' $( pwd ) /assets' " >> ~ /.grip/settings.py
```

Ekspor semua file Markdown Anda dengan Grip dan ganti jalur aset absolut dengan jalur relatif:

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

Anda juga dapat mengompresi kumpulan file HTML ke docs.tgz dengan:

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

Mencari solusi lintas platform? Berikut skrip Python yang setara.

Oleh Matthew R. Tanudjaja.

Konfigurasi

Untuk menyesuaikan Grip, buat ~/.grip/settings.py , lalu tambahkan satu atau beberapa variabel berikut:

HOST : Host yang akan digunakan ketika tidak disediakan sebagai argumen CLI, localhost secara default
PORT : Port yang digunakan ketika tidak disediakan sebagai argumen CLI, 6419 secara default
DEBUG : Apakah akan menggunakan debugger Flask ketika terjadi kesalahan, False secara default
DEBUG_GRIP : Mencetak informasi tambahan ketika terjadi kesalahan, False secara default
API_URL : URL dasar untuk API github, misalnya contoh Github Enterprise. https://api.github.com secara default
CACHE_DIRECTORY : Direktori, relatif terhadap ~/.grip , untuk menempatkan aset yang di-cache (ini dijalankan melalui filter berikut: CACHE_DIRECTORY.format(version=__version__) ), 'cache-{version}' secara default
AUTOREFRESH : Apakah akan secara otomatis me-refresh konten Readme ketika file berubah, True secara default
QUIET : Jangan mencetak informasi tambahan, False secara default
STYLE_URLS : URL tambahan yang akan ditambahkan ke halaman yang dirender, [] secara default
USERNAME : Nama pengguna yang digunakan ketika tidak disediakan sebagai argumen CLI, None secara default
PASSWORD : Kata sandi atau token akses pribadi yang akan digunakan ketika tidak diberikan sebagai argumen CLI ( Tolong jangan simpan kata sandi Anda di sini. Sebagai gantinya, gunakan token akses atau masukkan kode ini, ambil kata sandi Anda dari pengelola kata sandi), None secara default

Perhatikan bahwa ini adalah file Python. Jika Anda melihat kesalahan 'X' is not defined , Anda mungkin mengabaikan beberapa tanda kutip. Misalnya:

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

Variabel lingkungan

GRIPHOME : Tentukan lokasi settings.py alternatif, ~/.grip secara default
GRIPURL : URL server Grip, /__/grip secara default

Canggih

File ini adalah skrip Python biasa, jadi Anda dapat menambahkan konfigurasi lebih lanjut.

Misalnya, untuk membaca setelan dari lingkungan dan memberikan nilai default saat tidak disetel:

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

API

Anda dapat mengakses API secara langsung dengan Python, menggunakannya dalam proyek Anda sendiri:

 from grip import serve

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

Jalankan main secara langsung:

 from grip import main

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

Atau akses aplikasi Flask yang mendasarinya untuk lebih banyak fleksibilitas:

 from grip import create_app

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

Dokumentasi

melayani

Menjalankan server lokal dan merender file Readme yang terletak di path saat dikunjungi di browser.

 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 : Nama file yang akan dirender, atau direktori yang berisi file Readme Anda, defaultnya adalah direktori kerja saat ini
host : Host yang akan didengarkan, secara default menggunakan variabel konfigurasi HOST
port : Port untuk didengarkan, defaultnya adalah variabel konfigurasi PORT
user_content : Apakah akan merender dokumen sebagai konten pengguna seperti komentar atau masalah pengguna
context : Konteks proyek yang akan digunakan ketika user_content benar, yang berbentuk username/project
username : Pengguna yang akan diautentikasi dengan GitHub untuk memperluas batas API
password : Kata sandi untuk mengautentikasi dengan GitHub untuk memperluas batas API
render_offline : Apakah akan merender secara lokal menggunakan Python-Markdown (Catatan: ini masih dalam proses)
render_wide : Apakah akan merender halaman lebar, False secara default (ini tidak berpengaruh bila digunakan dengan user_content )
render_inline : Apakah akan memasukkan gaya ke dalam file HTML
api_url : URL dasar yang berbeda untuk API github, misalnya contoh Github Enterprise. Defaultnya adalah API publik https://api.github.com.
title : Judul halaman, berasal dari path secara default
autorefresh : Secara otomatis memperbarui konten yang dirender ketika file Readme berubah, True secara default
browser : Membuka tab di browser setelah server dimulai., False secara default
grip_class : Gunakan kelas Grip khusus

ekspor

Menulis file Readme yang ditentukan ke file HTML dengan gaya dan aset sebaris.

 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 : Nama file yang akan dirender, atau direktori yang berisi file Readme Anda, defaultnya adalah direktori kerja saat ini
user_content : Apakah akan merender dokumen sebagai konten pengguna seperti komentar atau masalah pengguna
context : Konteks proyek yang akan digunakan ketika user_content benar, yang berbentuk username/project
username : Pengguna yang akan diautentikasi dengan GitHub untuk memperluas batas API
password : Kata sandi untuk mengautentikasi dengan GitHub untuk memperluas batas API
render_offline : Apakah akan merender secara lokal menggunakan Python-Markdown (Catatan: ini masih dalam proses)
render_wide : Apakah akan merender halaman lebar, False secara default (ini tidak berpengaruh bila digunakan dengan user_content )
render_inline : Apakah akan memasukkan gaya dalam file HTML (Catatan: tidak seperti fungsi API lainnya, defaultnya adalah True )
out_filename : Nama file yang akan ditulis, .html secara default
api_url : URL dasar yang berbeda untuk API github, misalnya contoh Github Enterprise. Defaultnya adalah API publik https://api.github.com.
title : Judul halaman, berasal dari path secara default
quiet : Jangan mencetak ke terminal
theme : Tema untuk melihat file penurunan harga (mode terang atau mode gelap). Opsi yang valid ("terang", "gelap"). Bawaan: "ringan".
grip_class : Gunakan kelas Grip khusus

buat_aplikasi

Membuat aplikasi Flask yang dapat Anda gunakan untuk merender dan menyajikan file Readme. Ini adalah aplikasi yang sama yang digunakan untuk serve dan export serta menginisialisasi cache, menggunakan gaya cache jika tersedia.

 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 : Nama file yang akan dirender, atau direktori yang berisi file Readme Anda, defaultnya adalah direktori kerja saat ini
user_content : Apakah akan merender dokumen sebagai konten pengguna seperti komentar atau masalah pengguna
context : Konteks proyek yang akan digunakan ketika user_content benar, yang berbentuk username/project
username : Pengguna yang akan diautentikasi dengan GitHub untuk memperluas batas API
password : Kata sandi untuk mengautentikasi dengan GitHub untuk memperluas batas API
render_offline : Apakah akan merender secara lokal menggunakan Python-Markdown (Catatan: ini masih dalam proses)
render_wide : Apakah akan merender halaman lebar, False secara default (ini tidak berpengaruh bila digunakan dengan user_content )
render_inline : Apakah akan memasukkan gaya ke dalam file HTML
api_url : URL dasar yang berbeda untuk API github, misalnya contoh Github Enterprise. Defaultnya adalah API publik https://api.github.com.
title : Judul halaman, berasal dari path secara default
text : String atau aliran teks Markdown untuk dirender alih-alih dimuat dari path (Catatan: path dapat digunakan untuk mengatur judul halaman)
grip_class : Gunakan kelas Grip khusus

render_app

Merender aplikasi yang dibuat oleh create_app dan mengembalikan HTML yang biasanya muncul saat mengunjungi rute tersebut.

 render_app ( app , route = '/' )

app : Aplikasi Flask yang akan dirender
route : Rute untuk dirender, '/' secara default

render_konten

Merender teks penurunan harga yang ditentukan tanpa cache.

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

text : Teks penurunan harga yang akan dirender
user_content : Apakah akan merender dokumen sebagai konten pengguna seperti komentar atau masalah pengguna
context : Konteks proyek yang akan digunakan ketika user_content benar, yang berbentuk username/project
username : Pengguna yang akan diautentikasi dengan GitHub untuk memperluas batas API
password : Kata sandi untuk mengautentikasi dengan GitHub untuk memperluas batas API
render_offline : Apakah akan merender secara lokal menggunakan Python-Markdown (Catatan: ini masih dalam proses)
api_url : URL dasar yang berbeda untuk API github, misalnya contoh Github Enterprise. Ini diperlukan saat tidak menggunakan penyaji offline.
title : Judul halaman, berasal dari path secara default

render_halaman

Merender penurunan harga dari jalur atau teks yang ditentukan, tanpa cache, dan mengembalikan halaman HTML yang menyerupai tampilan GitHub Readme.

 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 : Jalur yang digunakan untuk judul halaman, menampilkan 'README.md' jika Tidak Ada
user_content : Apakah akan merender dokumen sebagai konten pengguna seperti komentar atau masalah pengguna
context : Konteks proyek yang akan digunakan ketika user_content benar, yang berbentuk username/project
username : Pengguna yang akan diautentikasi dengan GitHub untuk memperluas batas API
password : Kata sandi untuk mengautentikasi dengan GitHub untuk memperluas batas API
render_offline : Apakah akan merender secara offline menggunakan Python-Markdown (Catatan: ini sedang dalam proses)
render_wide : Apakah akan merender halaman lebar, False secara default (ini tidak berpengaruh bila digunakan dengan user_content )
render_inline : Apakah akan memasukkan gaya ke dalam file HTML
api_url : URL dasar yang berbeda untuk API github, misalnya contoh Github Enterprise. Defaultnya adalah API publik https://api.github.com.
title : Judul halaman, berasal dari path secara default
text : String atau aliran teks Markdown untuk dirender alih-alih dimuat dari path (Catatan: path dapat digunakan untuk mengatur judul halaman)
quiet : Jangan mencetak ke terminal
theme : Tema untuk melihat file penurunan harga (mode terang atau mode gelap). Opsi yang valid ("terang", "gelap"). Bawaan: "ringan".
grip_class : Gunakan kelas Grip khusus

hapus_cache

Menghapus gaya dan aset yang di-cache.

 clear_cache ( grip_class = None )

utama

Menjalankan Grip dengan argumen yang ditentukan.

 main ( argv = None , force_utf8 = True )

argv : Argumen yang akan dijalankan, sys.argv[1:] secara default
force_utf8 : Menyetel pengkodean default ke utf-8 dalam instance Python saat ini. Ini tidak berpengaruh pada Python 3 karena Unicode ditangani secara default

Kelas

pegangan kelas(Labu)

Aplikasi Flask yang dapat menyajikan file atau direktori yang berisi 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 )

default_renderer

Mengembalikan penyaji default menggunakan konfigurasi saat ini. Ini hanya digunakan jika penyaji diatur ke Tidak Ada di konstruktor.

 Grip . default_renderer ()

default_asset_manager

Mengembalikan manajer aset default menggunakan konfigurasi saat ini. Ini hanya digunakan jika aset_manager diatur ke Tidak Ada di konstruktor.

 Grip . default_asset_manager ()

tambahkan_content_types

Menambahkan tipe konten application/x-font-woff dan application/octet-stream jika tidak ada. Ganti untuk menambahkan tipe konten tambahan pada inisialisasi.

 Grip . add_content_types ()

hapus_cache

Menghapus aset yang diunduh.

 Grip . clear_cache ()

memberikan

Merender aplikasi dan mengembalikan unicode HTML yang biasanya muncul saat berkunjung di browser.

 Grip . render ( route = None )

route : Rute untuk dirender, / secara default

berlari

Memulai server untuk merender README. Ini memanggil Flask.run secara internal.

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

host : Nama host untuk didengarkan. Setel ini ke '0.0.0.0' agar server juga tersedia secara eksternal, 'localhost' secara default
port : Port server web. Defaultnya adalah 6419
debug : Jika diberikan, aktifkan atau nonaktifkan mode debug. Lihat Flask.debug.
use_reloader : Haruskah server secara otomatis memulai ulang proses python jika modul diubah? False secara default kecuali setelan DEBUG_GRIP ditentukan.
open_browser : Membuka browser ke alamat saat server dimulai

kelas SudahRunningError(RuntimeError)

Dibesarkan ketika Grip.run dipanggil saat server sudah berjalan.

 AlreadyRunningError ()

kelas ReadmeNotFoundError(NotFoundError atau IOError)

Dibesarkan ketika Readme yang ditentukan tidak dapat ditemukan.

 ReadmeNotFoundError ( path = None , message = None )

kelas ReadmeAssetManager(objek)

Mengelola aset gaya dan font yang dirender dengan halaman Readme. Ini adalah kelas dasar abstrak.

 ReadmeAssetManager ( cache_path , style_urls = None )

kelas GitHubAssetManager(ReadmeAssetManager)

Mengelola aset gaya dan font yang dirender dengan halaman Readme. Setel cache_path ke Tidak Ada untuk menonaktifkan cache.

kelas ReadmeReader (objek)

Membaca konten Readme dari subjalur URL. Ini adalah kelas dasar abstrak.

 ReadmeReader ()

kelas DirectoryReader (ReadmeReader)

Membaca file Readme dari subjalur URL.

 DirectoryReader ( path = None , silent = False )

kelas Pembaca Teks(ReadmeReader)

Membaca konten Readme dari string unicode yang disediakan.

 TextReader ( text , display_filename = None )

kelas StdinReader(Pembaca Teks)

Membaca teks Readme dari STDIN.

 StdinReader ( display_filename = None )

kelas ReadmeRenderer (objek)

Merender Readme. Ini adalah kelas dasar abstrak.

 ReadmeRenderer ( user_content = None , context = None )

kelas GitHubRenderer(ReadmeRenderer)

Merender Readme yang ditentukan menggunakan GitHub Markdown API.

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

kelas OfflineRenderer(ReadmeRenderer)

Merender Readme yang ditentukan secara lokal menggunakan Python murni. Catatan: Saat ini fitur ini belum lengkap.

 OfflineRenderer ( user_content = None , context = None )

Konstanta

SUPPORTED_TITLES

Judul file Markdown yang umum di GitHub.

 SUPPORTED_TITLES = [ 'README' , 'Home' ]

filename : File UTF-8 yang akan dibaca.

DIDUKUNG_EXTENSIONS

Ekstensi yang didukung, sebagaimana ditentukan oleh GitHub.

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

DEFAULT_FILENAMES

Konstanta ini berisi nama yang dicari Grip ketika tidak ada file yang disediakan.

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

DEFAULT_NAMA FILE

Konstanta ini berisi nama file default Readme, yaitu:

 DEFAULT_FILENAME = DEFAULT_FILENAMES [ 0 ]  # README.md

DEFAULT_GRIPHOME

Konstanta ini menunjuk ke nilai default jika variabel lingkungan GRIPHOME tidak ditentukan.

 DEFAULT_GRIPHOME = '~/.grip'

DEFAULT_GRIPURL

URL default server Grip dan semua asetnya:

 DEFAULT_GRIPURL = '/__/grip'

DEFAULT_API_URL

Nilai default app_url:

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

Pengujian

Instal paket dan persyaratan pengujian:

$ pip install -e .[tests]

Jalankan tes dengan pytest:

$ pytest

Atau untuk menjalankan kembali pengujian saat Anda melakukan perubahan, gunakan pytest-watch:

$ ptw

Tes asumsi eksternal

Jika Anda mengalami masalah dengan Grip, kemungkinan asumsi yang dibuat tentang GitHub API telah dilanggar. Untuk memverifikasi ini, jalankan:

$ pytest -m assumption

Karena asumsi eksternal bergantung pada koneksi internet, Anda mungkin ingin melewatkannya saat mengembangkan secara lokal. Kencangkan siklus lebih jauh lagi dengan menghentikan kegagalan pertama dengan -x :

$ pytest -xm " not assumption "

Atau dengan jam tangan pytest:

$ ptw -- -xm " not assumption "

Berkontribusi

Periksa terbitan yang masih terbuka atau buka terbitan baru untuk memulai diskusi seputar ide fitur atau bug yang Anda temukan
Cabangkan repositori dan buat perubahan Anda
Buka permintaan tarik baru

Jika PR Anda sudah menunggu cukup lama, silakan hubungi saya di Twitter.

Sering menggunakan perangkat lunak ini? ?

Memperluas