Descarga de grip - Descarga del código fuente de grip

Grip - Vista previa instantánea Léame de GitHub

Procese archivos Léame locales antes de enviarlos a GitHub.

Grip es una aplicación de servidor de línea de comandos escrita en Python que utiliza la API de rebajas de GitHub para representar un archivo Léame local. Los estilos y la representación provienen directamente de GitHub, por lo que sabrás exactamente cómo aparecerá. Los cambios que realice en el archivo Léame se reflejarán instantáneamente en el navegador sin necesidad de actualizar la página.

Motivación

A veces, solo desea ver el resultado exacto del archivo Léame antes de confirmar y enviar a GitHub.

Especialmente cuando se realiza un desarrollo basado en Léame.

Instalación

Para instalar el agarre, simplemente:

$ pip install grip

En OS X, también puedes instalar con Homebrew:

$ brew install grip

Uso

Para representar el archivo Léame de un repositorio:

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

Ahora abra un navegador y visite http://localhost:6419. O ejecute -b y Grip abrirá una nueva pestaña del navegador.

También puede especificar un puerto:

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

O un archivo explícito:

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

Alternativamente, puede simplemente ejecutar grip y visitar localhost:6419/AUTHORS.md ya que grip admite URL relativas.

Puedes combinar los ejemplos anteriores. O especifique un nombre de host en lugar de un puerto. O proporcione ambos.

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

Incluso puedes omitir el servidor y exportar a un único archivo HTML, con todos los estilos y recursos integrados:

$ grip --export
Exporting to README.html

Controle el nombre de salida con el segundo argumento:

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

Si está exportando una gran cantidad de archivos, puede evitar que los estilos se incluyan en línea para ahorrar espacio con --no-inline :

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

También se admite la lectura y escritura desde stdin y stdout , lo que le permite usar Grip con otros programas:

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

$ grip AUTHORS.md --export - | bcat

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

Esto le permite probar rápidamente cómo se ven las cosas ingresando Markdown directamente en su terminal:

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

Nota: ^D significa Ctrl+D , que funciona en Linux y OS X. En Windows tendrás que usar Ctrl+Z .

También se admite la representación como contenido del usuario, como comentarios y problemas , con un contexto de repositorio opcional para vincular a los problemas:

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

Para obtener más detalles y opciones adicionales, consulte la ayuda:

$ grip -h

Acceso

Grip se esfuerza por estar lo más cerca posible de GitHub. Para lograr esto, grip utiliza la API Markdown de GitHub para que los cambios en su motor de renderizado se reflejen inmediatamente sin necesidad de actualizar grip. Sin embargo, debido a esto, es posible que alcances el límite de tarifa por hora de la API. Si esto sucede, grip ofrece una forma de acceder a la API utilizando sus credenciales para desbloquear un límite de velocidad mucho más alto.

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

O use un token de acceso personal con un alcance vacío (tenga en cuenta que se requiere un token si su cuenta de GitHub está configurada con autenticación de dos factores):

$ grip --pass < token >

Puede conservar estas opciones en su configuración local. Por motivos de seguridad, se recomienda encarecidamente utilizar un token de acceso en lugar de una contraseña . (También puedes mantener tu contraseña segura configurando Grip para que obtenga tu contraseña de un administrador de contraseñas).

También hay una rama de trabajo en progreso para proporcionar renderizado sin conexión . Una vez que esto se parezca más precisamente a GitHub, se expondrá en la CLI y, en última instancia, se utilizará como un motor alternativo perfecto para cuando no se pueda acceder a la API.

Grip siempre accede a GitHub a través de HTTPS, por lo que su archivo README y sus credenciales están protegidos.

Consejos

Así es como otros miembros de la comunidad utilizan Grip.

¿Quieres compartir el tuyo? Saluda a @joeyespo o envía una solicitud de extracción.

Crear un espejo local de un Wiki de Github

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

Por Josué Gourneau.

Genere documentación HTML a partir de una colección de archivos README vinculados

Ingrese al directorio:

$ cd YOUR_DIR
$ export GRIPURL= $( pwd )

Incluya todos los activos configurando la variable de configuración CACHE_DIRECTORY :
> ~/.grip/settings.py">
```
$ echo " CACHE_DIRECTORY = ' $( pwd ) /assets' " >> ~ /.grip/settings.py
```

Exporte todos sus archivos Markdown con Grip y reemplace las rutas absolutas de los activos con rutas relativas:

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

Opcionalmente, puedes comprimir el conjunto de archivos HTML en docs.tgz con:

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

¿Busca una solución multiplataforma? Aquí hay un script de Python equivalente.

Por Matthew R. Tanudjaja.

Configuración

Para personalizar Grip, cree ~/.grip/settings.py y luego agregue una o más de las siguientes variables:

HOST : el host que se utilizará cuando no se proporcione como argumento CLI, localhost de forma predeterminada
PORT : El puerto que se utilizará cuando no se proporcione como argumento CLI, 6419 de forma predeterminada
DEBUG : si se debe utilizar el depurador de Flask cuando ocurre un error, False de forma predeterminada
DEBUG_GRIP : Imprime información extendida cuando ocurre un error, False por defecto
API_URL : URL base para la API de github, por ejemplo la de una instancia de Github Enterprise. https://api.github.com por defecto
CACHE_DIRECTORY : el directorio, relativo a ~/.grip , para colocar los activos almacenados en caché (esto se ejecuta a través del siguiente filtro: CACHE_DIRECTORY.format(version=__version__) ), 'cache-{version}' de forma predeterminada
AUTOREFRESH : si se actualiza automáticamente el contenido Léame cuando el archivo cambia, True de forma predeterminada
QUIET : No imprimir información extendida, False por defecto
STYLE_URLS : URL adicionales que se agregarán a la página representada, [] de forma predeterminada
USERNAME : El nombre de usuario que se utilizará cuando no se proporcione como argumento CLI; None de forma predeterminada
PASSWORD : la contraseña o el token de acceso personal que se utilizará cuando no se proporcione como argumento CLI ( no guarde sus contraseñas aquí. En su lugar, utilice un token de acceso o introduzca este código para obtener su contraseña de un administrador de contraseñas), None de forma predeterminada.

Tenga en cuenta que este es un archivo Python. Si ve errores 'X' is not defined , es posible que haya pasado por alto algunas citas. Por ejemplo:

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

Variables ambientales

GRIPHOME : especifique una ubicación alternativa settings.py , ~/.grip de forma predeterminada
GRIPURL : La URL del servidor Grip, /__/grip por defecto

Avanzado

Este archivo es un script Python normal, por lo que puede agregar una configuración más avanzada.

Por ejemplo, para leer una configuración del entorno y proporcionar un valor predeterminado cuando no está configurado:

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

API

Puedes acceder a la API directamente con Python, usándola en tus propios proyectos:

 from grip import serve

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

Ejecute principal directamente:

 from grip import main

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

O acceda a la aplicación Flask subyacente para obtener aún más flexibilidad:

 from grip import create_app

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

Documentación

atender

Ejecuta un servidor local y procesa el archivo Léame ubicado en path cuando se visita en el navegador.

 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 : el nombre del archivo a representar, o el directorio que contiene su archivo Léame, de forma predeterminada el directorio de trabajo actual
host : el host en el que escuchar, de forma predeterminada la variable de configuración HOST
port : El puerto para escuchar, de forma predeterminada la variable de configuración PORT
user_content : si se debe representar un documento como contenido del usuario, como comentarios o problemas del usuario.
context : el contexto del proyecto que se utilizará cuando user_content es verdadero, que toma la forma de username/project
username : el usuario que se autenticará con GitHub para ampliar el límite de API
password : la contraseña para autenticarse con GitHub para ampliar el límite de API
render_offline : si se debe renderizar localmente usando Python-Markdown (Nota: este es un trabajo en progreso)
render_wide : si se debe representar una página ancha, False de forma predeterminada (esto no tiene ningún efecto cuando se usa con user_content )
render_inline : si se deben alinear los estilos dentro del archivo HTML
api_url : una URL base diferente para la API de github, por ejemplo la de una instancia de Github Enterprise. La opción predeterminada es la API pública https://api.github.com.
title : El título de la página, derivado de path de forma predeterminada
autorefresh : actualiza automáticamente el contenido renderizado cuando cambia el archivo Léame, True de forma predeterminada
browser : abre una pestaña en el navegador después de que se inicia el servidor. False de forma predeterminada
grip_class : utiliza una clase de agarre personalizada

exportar

Escribe el archivo Léame especificado en un archivo HTML con estilos y recursos incorporados.

 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 : el nombre del archivo a representar, o el directorio que contiene su archivo Léame, de forma predeterminada el directorio de trabajo actual
user_content : si se debe representar un documento como contenido del usuario, como comentarios o problemas del usuario.
context : el contexto del proyecto que se utilizará cuando user_content es verdadero, que toma la forma de username/project
username : el usuario que se autenticará con GitHub para ampliar el límite de API
password : la contraseña para autenticarse con GitHub para ampliar el límite de API
render_offline : si se debe renderizar localmente usando Python-Markdown (Nota: este es un trabajo en progreso)
render_wide : si se debe representar una página ancha, False de forma predeterminada (esto no tiene ningún efecto cuando se usa con user_content )
render_inline : si se deben alinear los estilos dentro del archivo HTML (Nota: a diferencia de otras funciones API, el valor predeterminado es True )
out_filename : el nombre de archivo en el que escribir, .html de forma predeterminada
api_url : una URL base diferente para la API de github, por ejemplo la de una instancia de Github Enterprise. La opción predeterminada es la API pública https://api.github.com.
title : El título de la página, derivado de path de forma predeterminada
quiet : no imprimir en el terminal
theme : Tema para ver el archivo de rebajas (modo claro u modo oscuro). Opciones válidas ("claro", "oscuro"). Valor predeterminado: "ligero".
grip_class : utiliza una clase de agarre personalizada

crear_aplicación

Crea una aplicación Flask que puede usar para renderizar y entregar los archivos Léame. Esta es la misma aplicación utilizada para serve y export e inicializa el caché, utilizando los estilos almacenados en caché cuando estén disponibles.

 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 : el nombre del archivo a representar, o el directorio que contiene su archivo Léame, de forma predeterminada el directorio de trabajo actual
user_content : si se debe representar un documento como contenido del usuario, como comentarios o problemas del usuario.
context : el contexto del proyecto que se utilizará cuando user_content es verdadero, que toma la forma de username/project
username : el usuario que se autenticará con GitHub para ampliar el límite de API
password : la contraseña para autenticarse con GitHub para ampliar el límite de API
render_offline : si se debe renderizar localmente usando Python-Markdown (Nota: este es un trabajo en progreso)
render_wide : si se debe representar una página ancha, False de forma predeterminada (esto no tiene ningún efecto cuando se usa con user_content )
render_inline : si se deben alinear los estilos dentro del archivo HTML
api_url : una URL base diferente para la API de github, por ejemplo la de una instancia de Github Enterprise. La opción predeterminada es la API pública https://api.github.com.
title : El título de la página, derivado de path de forma predeterminada
text : una cadena o flujo de texto Markdown para representar en lugar de cargarse desde path (Nota: path se puede usar para establecer el título de la página)
grip_class : utiliza una clase de agarre personalizada

render_app

Representa la aplicación creada por create_app y devuelve el HTML que normalmente aparecería al visitar esa ruta.

 render_app ( app , route = '/' )

app : La aplicación Flask para renderizar
route : La ruta a renderizar, '/' por defecto

render_content

Representa el texto de rebajas especificado sin almacenamiento en caché.

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

text : El texto de Markdown para renderizar
user_content : si se debe representar un documento como contenido del usuario, como comentarios o problemas del usuario.
context : el contexto del proyecto que se utilizará cuando user_content es verdadero, que toma la forma de username/project
username : el usuario que se autenticará con GitHub para ampliar el límite de API
password : la contraseña para autenticarse con GitHub para ampliar el límite de API
render_offline : si se debe renderizar localmente usando Python-Markdown (Nota: este es un trabajo en progreso)
api_url : una URL base diferente para la API de github, por ejemplo la de una instancia de Github Enterprise. Esto es necesario cuando no se utiliza el renderizador sin conexión.
title : El título de la página, derivado de path de forma predeterminada

render_pagina

Representa la rebaja a partir de la ruta o el texto especificado, sin almacenamiento en caché, y devuelve una página HTML que se parece a la vista Léame de GitHub.

 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 : la ruta que se utilizará para el título de la página, representando 'README.md' si no hay ninguna
user_content : si se debe representar un documento como contenido del usuario, como comentarios o problemas del usuario.
context : el contexto del proyecto que se utilizará cuando user_content es verdadero, que toma la forma de username/project
username : el usuario que se autenticará con GitHub para ampliar el límite de API
password : la contraseña para autenticarse con GitHub para ampliar el límite de API
render_offline : si se debe renderizar sin conexión usando Python-Markdown (Nota: este es un trabajo en progreso)
render_wide : si se debe representar una página ancha, False de forma predeterminada (esto no tiene ningún efecto cuando se usa con user_content )
render_inline : si se deben alinear los estilos dentro del archivo HTML
api_url : una URL base diferente para la API de github, por ejemplo la de una instancia de Github Enterprise. La opción predeterminada es la API pública https://api.github.com.
title : El título de la página, derivado de path de forma predeterminada
text : una cadena o flujo de texto Markdown para representar en lugar de cargarse desde path (Nota: path se puede usar para establecer el título de la página)
quiet : no imprimir en el terminal
theme : Tema para ver el archivo de rebajas (modo claro u modo oscuro). Opciones válidas ("claro", "oscuro"). Valor predeterminado: "ligero".
grip_class : utiliza una clase de agarre personalizada

borrar_caché

Borra los estilos y activos almacenados en caché.

 clear_cache ( grip_class = None )

principal

Ejecuta Grip con los argumentos especificados.

 main ( argv = None , force_utf8 = True )

argv : Los argumentos para ejecutar, sys.argv[1:] por defecto
force_utf8 : establece la codificación predeterminada en utf-8 en la instancia actual de Python. Esto no tiene ningún efecto en Python 3 ya que Unicode se maneja de forma predeterminada.

Clases

agarre de clase (matraz)

Una aplicación Flask que puede servir un archivo o directorio que contiene un archivo 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 )

renderizador_predeterminado

Devuelve el renderizador predeterminado usando la configuración actual. Esto solo se usa si el procesador está configurado en Ninguno en el constructor.

 Grip . default_renderer ()

administrador_de_activos_predeterminado

Devuelve el administrador de activos predeterminado usando la configuración actual. Esto solo se usa si active_manager está configurado en Ninguno en el constructor.

 Grip . default_asset_manager ()

agregar_tipos_de_contenido

Agrega los tipos de contenido application/x-font-woff y application/octet-stream si faltan. Anular para agregar tipos de contenido adicionales en la inicialización.

 Grip . add_content_types ()

borrar_caché

Borra los recursos descargados.

 Grip . clear_cache ()

prestar

Representa la aplicación y devuelve el HTML Unicode que normalmente aparecería al visitarla en el navegador.

 Grip . render ( route = None )

route : La ruta a renderizar, / por defecto

correr

Inicia un servidor para representar el archivo README. Esto llama a Flask.run internamente.

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

host : el nombre de host para escuchar. Establezca esto en '0.0.0.0' para que el servidor también esté disponible externamente, 'localhost' de forma predeterminada
port : El puerto del servidor web. El valor predeterminado es 6419
debug : si se proporciona, habilite o deshabilite el modo de depuración. Consulte Flask.debug.
use_reloader : ¿Debería el servidor reiniciar automáticamente el proceso de Python si se cambiaron los módulos? False de forma predeterminada a menos que se especifique la configuración DEBUG_GRIP .
open_browser : abre el navegador en la dirección cuando se inicia el servidor

clase YaRunningError(RuntimeError)

Se genera cuando se llama Grip.run mientras el servidor ya se está ejecutando.

 AlreadyRunningError ()

clase ReadmeNotFoundError(NotFoundError o IOError)

Se genera cuando no se puede encontrar el archivo Léame especificado.

 ReadmeNotFoundError ( path = None , message = None )

clase ReadmeAssetManager(objeto)

Gestiona los recursos de estilo y fuente representados con páginas Léame. Esta es una clase base abstracta.

 ReadmeAssetManager ( cache_path , style_urls = None )

clase GitHubAssetManager (LéameAssetManager)

Gestiona los recursos de estilo y fuente representados con páginas Léame. Establezca cache_path en Ninguno para deshabilitar el almacenamiento en caché.

clase LéameReader(objeto)

Lee el contenido Léame de una subruta URL. Esta es una clase base abstracta.

 ReadmeReader ()

clase DirectoryReader(ReadmeReader)

Lee archivos Léame de subrutas URL.

 DirectoryReader ( path = None , silent = False )

clase TextReader (LéameReader)

Lee el contenido Léame de la cadena Unicode proporcionada.

 TextReader ( text , display_filename = None )

clase StdinReader(TextReader)

Lee el texto Léame de STDIN.

 StdinReader ( display_filename = None )

clase ReadmeRenderer(objeto)

Representa el archivo Léame. Esta es una clase base abstracta.

 ReadmeRenderer ( user_content = None , context = None )

clase GitHubRenderer (ReadmeRenderer)

Representa el archivo Léame especificado mediante la API de GitHub Markdown.

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

clase OfflineRenderer (ReadmeRenderer)

Representa el archivo Léame especificado localmente usando Python puro. Nota: Esta es actualmente una característica incompleta.

 OfflineRenderer ( user_content = None , context = None )

Constantes

TÍTULOS_APOYADOS

Los títulos de archivos Markdown comunes en GitHub.

 SUPPORTED_TITLES = [ 'README' , 'Home' ]

filename : El archivo UTF-8 a leer.

EXTENSIONES_SOPORTADAS

Las extensiones admitidas, según lo definido por GitHub.

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

DEFAULT_FILENAMES

Esta constante contiene los nombres que busca Grip cuando no se proporciona ningún archivo.

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

DEFAULT_FILENAME

Esta constante contiene el nombre de archivo Léame predeterminado, a saber:

 DEFAULT_FILENAME = DEFAULT_FILENAMES [ 0 ]  # README.md

DEFAULT_GRIPHOME

Esta constante apunta al valor predeterminado si no se especifica la variable de entorno GRIPHOME .

 DEFAULT_GRIPHOME = '~/.grip'

DEFAULT_GRIPURL

La URL predeterminada del servidor Grip y todos sus activos:

 DEFAULT_GRIPURL = '/__/grip'

DEFAULT_API_URL

El valor predeterminado de app_url:

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

Pruebas

Instale el paquete y pruebe los requisitos:

$ pip install -e .[tests]

Ejecute pruebas con pytest:

$ pytest

O para volver a ejecutar pruebas a medida que realiza cambios, use pytest-watch:

$ ptw

Pruebas de supuestos externos

Si tiene un problema con Grip, es probable que se haya roto una suposición hecha sobre la API de GitHub. Para verificar esto, ejecute:

$ pytest -m assumption

Dado que los supuestos externos dependen de una conexión a Internet, es posible que desee omitirlos al desarrollar localmente. Apriete el ciclo aún más deteniéndose en el primer fallo con -x :

$ pytest -xm " not assumption "

O con pytest-watch:

$ ptw -- -xm " not assumption "

Contribuyendo

Verifique los problemas abiertos o abra un nuevo problema para iniciar una discusión sobre su idea de función o el error que encontró.
Bifurca el repositorio y haz tus cambios
Abrir una nueva solicitud de extracción

Si su PR ha estado esperando un tiempo, no dude en enviarme un ping en Twitter.

¿Utiliza este software con frecuencia? ?

Expandir