download do aperto - download do código-fonte do aperto

Grip – Visualização instantânea do Leiame do GitHub

Renderize arquivos leia-me locais antes de enviá-los para o GitHub.

Grip é um aplicativo de servidor de linha de comando escrito em Python que usa a API markdown do GitHub para renderizar um arquivo leia-me local. Os estilos e a renderização vêm diretamente do GitHub, então você saberá exatamente como eles aparecerão. As alterações feitas no Leiame serão refletidas instantaneamente no navegador sem a necessidade de atualização da página.

Motivação

Às vezes, você só deseja ver o resultado exato do leia-me antes de enviar e enviar para o GitHub.

Especialmente ao fazer desenvolvimento orientado por Readme.

Instalação

Para instalar o grip, basta:

$ pip install grip

No OS X, você também pode instalar com Homebrew:

$ brew install grip

Uso

Para renderizar o leia-me de um repositório:

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

Agora abra um navegador e visite http://localhost:6419. Ou execute -b e o Grip abrirá uma nova guia do navegador para você.

Você também pode especificar uma porta:

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

Ou um arquivo explícito:

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

Alternativamente, você pode simplesmente executar grip e visitar localhost:6419/AUTHORS.md, pois o grip suporta URLs relativos.

Você pode combinar os exemplos anteriores. Ou especifique um nome de host em vez de uma porta. Ou forneça 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/

Você pode até ignorar o servidor e exportar para um único arquivo HTML, com todos os estilos e recursos incorporados:

$ grip --export
Exporting to README.html

Controle o nome da saída com o segundo argumento:

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

Se você estiver exportando vários arquivos, poderá impedir que os estilos sejam incorporados para economizar espaço com --no-inline :

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

A leitura e gravação de stdin e stdout também são suportadas, permitindo usar o Grip com outros programas:

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

$ grip AUTHORS.md --export - | bcat

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

Isso permite que você teste rapidamente a aparência das coisas inserindo Markdown diretamente em seu terminal:

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

Nota: ^D significa Ctrl+D , que funciona no Linux e OS X. No Windows você terá que usar Ctrl+Z .

A renderização como conteúdo do usuário, como comentários e problemas , também é suportada, com um contexto de repositório opcional para vincular aos problemas:

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

Para mais detalhes e opções adicionais, consulte a ajuda:

$ grip -h

Acesso

O Grip se esforça para estar o mais próximo possível do GitHub. Para fazer isso, o grip usa a API Markdown do GitHub para que as alterações em seu mecanismo de renderização sejam refletidas imediatamente, sem exigir que você atualize o grip. No entanto, por causa disso, você pode atingir o limite de taxa horária da API. Se isso acontecer, o grip oferece uma maneira de acessar a API usando suas credenciais para desbloquear um limite de taxa muito mais alto.

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

Ou use um token de acesso pessoal com escopo vazio (observe que um token será necessário se sua conta GitHub estiver configurada com autenticação de dois fatores):

$ grip --pass < token >

Você pode persistir essas opções na sua configuração local. Por motivos de segurança, é altamente recomendável usar um token de acesso em vez de uma senha . (Você também pode manter sua senha segura configurando o Grip para obtê-la de um gerenciador de senhas.)

Há também uma ramificação em andamento para fornecer renderização offline . Uma vez que isso se assemelhe mais precisamente ao GitHub, ele será exposto na CLI e, em última análise, será usado como um mecanismo substituto perfeito para quando a API não puder ser acessada.

O Grip sempre acessa o GitHub por HTTPS, portanto, seu README e suas credenciais ficam protegidos.

Pontas

Veja como outras pessoas da comunidade estão usando o Grip.

Quer compartilhar o seu próprio? Diga olá @joeyespo ou envie uma solicitação pull.

Crie um espelho local de um Wiki do Github

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

Por Joshua Gourneau.

Gere documentação HTML a partir de uma coleção de arquivos README vinculados

Entre no diretório:

$ cd YOUR_DIR
$ export GRIPURL= $( pwd )

Inclua todos os ativos definindo a variável de configuração CACHE_DIRECTORY :
> ~/.grip/settings.py">
```
$ echo " CACHE_DIRECTORY = ' $( pwd ) /assets' " >> ~ /.grip/settings.py
```

Exporte todos os seus arquivos Markdown com Grip e substitua caminhos absolutos de ativos por caminhos relativos:

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

Opcionalmente, você pode compactar o conjunto de arquivos HTML em docs.tgz com:

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

Procurando uma solução multiplataforma? Aqui está um script Python equivalente.

Por Matthew R. Tanudjaja.

Configuração

Para personalizar o Grip, crie ~/.grip/settings.py e adicione uma ou mais das seguintes variáveis:

HOST : O host a ser usado quando não for fornecido como argumento CLI, localhost por padrão
PORT : A porta a ser usada quando não fornecida como argumento CLI, 6419 por padrão
DEBUG : Se deve usar o depurador do Flask quando ocorre um erro, False por padrão
DEBUG_GRIP : Imprime informações estendidas quando ocorre um erro, False por padrão
API_URL : URL base para a API do github, por exemplo, de uma instância do Github Enterprise. https://api.github.com por padrão
CACHE_DIRECTORY : O diretório, relativo a ~/.grip , para colocar os ativos em cache (isso é executado através do seguinte filtro: CACHE_DIRECTORY.format(version=__version__) ), 'cache-{version}' por padrão
AUTOREFRESH : Se o conteúdo Leiame deve ser atualizado automaticamente quando o arquivo for alterado, True por padrão
QUIET : Não imprime informações estendidas, False por padrão
STYLE_URLS : URLs adicionais que serão adicionados à página renderizada, [] por padrão
USERNAME : O nome de usuário a ser usado quando não fornecido como argumento CLI, None por padrão
PASSWORD : A senha ou token de acesso pessoal a ser usado quando não for fornecido como um argumento CLI ( por favor, não salve suas senhas aqui. Em vez disso, use um token de acesso ou insira este código e pegue sua senha de um gerenciador de senhas), None por padrão

Observe que este é um arquivo Python. Se você vir erros 'X' is not defined , você pode ter esquecido algumas aspas. Por exemplo:

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

Variáveis de ambiente

GRIPHOME : Especifique um local alternativo settings.py , ~/.grip por padrão
GRIPURL : A URL do servidor Grip, /__/grip por padrão

Avançado

Este arquivo é um script Python normal, então você pode adicionar configurações mais avançadas.

Por exemplo, para ler uma configuração do ambiente e fornecer um valor padrão quando não estiver definido:

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

API

Você pode acessar a API diretamente com Python, usando-a em seus próprios projetos:

 from grip import serve

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

Execute main diretamente:

 from grip import main

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

Ou acesse o aplicativo Flask subjacente para obter ainda mais flexibilidade:

 from grip import create_app

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

Documentação

servir

Executa um servidor local e renderiza o arquivo Leiame localizado no path quando visitado no 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 : O nome do arquivo a ser renderizado ou o diretório que contém seu arquivo Leiame, padronizando o diretório de trabalho atual
host : O host para escutar, padronizando a variável de configuração HOST
port : A porta para escutar, padronizando a variável de configuração PORT
user_content : se deve renderizar um documento como conteúdo do usuário, como comentários ou problemas do usuário
context : o contexto do projeto a ser usado quando user_content for verdadeiro, que assume a forma de username/project
username : o usuário a ser autenticado no GitHub para estender o limite da API
password : a senha para autenticação no GitHub para estender o limite da API
render_offline : se deve renderizar localmente usando Python-Markdown (Nota: este é um trabalho em andamento)
render_wide : Se deve renderizar uma página larga, False por padrão (isso não tem efeito quando usado com user_content )
render_inline : Se os estilos devem ser incorporados no arquivo HTML
api_url : um URL base diferente para a API do github, por exemplo, o de uma instância do Github Enterprise. O padrão é a API pública https://api.github.com.
title : o título da página, derivado do path por padrão
autorefresh : atualiza automaticamente o conteúdo renderizado quando o arquivo Leiame é alterado, True por padrão
browser : abre uma guia no navegador após o servidor iniciar., False por padrão
grip_class : Use uma classe Grip personalizada

exportar

Grava o arquivo Leiame especificado em um arquivo HTML com estilos e recursos embutidos.

 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 : O nome do arquivo a ser renderizado ou o diretório que contém seu arquivo Leiame, padronizando o diretório de trabalho atual
user_content : se deve renderizar um documento como conteúdo do usuário, como comentários ou problemas do usuário
context : o contexto do projeto a ser usado quando user_content for verdadeiro, que assume a forma de username/project
username : o usuário a ser autenticado no GitHub para estender o limite da API
password : a senha para autenticação no GitHub para estender o limite da API
render_offline : se deve renderizar localmente usando Python-Markdown (Nota: este é um trabalho em andamento)
render_wide : Se deve renderizar uma página larga, False por padrão (isso não tem efeito quando usado com user_content )
render_inline : Se os estilos devem ser incorporados no arquivo HTML (Nota: ao contrário de outras funções da API, o padrão é True )
out_filename : O nome do arquivo no qual gravar, .html por padrão
api_url : um URL base diferente para a API do github, por exemplo, o de uma instância do Github Enterprise. O padrão é a API pública https://api.github.com.
title : o título da página, derivado do path por padrão
quiet : não imprime no terminal
theme : Tema para visualizar o arquivo markdown (modo claro ou modo escuro). Opções válidas ("claro", "escuro"). Padrão: "leve".
grip_class : Use uma classe Grip personalizada

criar_app

Cria um aplicativo Flask que você pode usar para renderizar e servir os arquivos Leiame. Este é o mesmo aplicativo usado para serve e export e inicializa o cache, usando os estilos armazenados em cache, quando disponíveis.

 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 : O nome do arquivo a ser renderizado ou o diretório que contém seu arquivo Leiame, padronizando o diretório de trabalho atual
user_content : se deve renderizar um documento como conteúdo do usuário, como comentários ou problemas do usuário
context : o contexto do projeto a ser usado quando user_content for verdadeiro, que assume a forma de username/project
username : o usuário a ser autenticado no GitHub para estender o limite da API
password : a senha para autenticação no GitHub para estender o limite da API
render_offline : se deve renderizar localmente usando Python-Markdown (Nota: este é um trabalho em andamento)
render_wide : Se deve renderizar uma página larga, False por padrão (isso não tem efeito quando usado com user_content )
render_inline : Se os estilos devem ser incorporados no arquivo HTML
api_url : um URL base diferente para a API do github, por exemplo, o de uma instância do Github Enterprise. O padrão é a API pública https://api.github.com.
title : o título da página, derivado do path por padrão
text : uma string ou fluxo de texto Markdown para renderizar em vez de ser carregado do path (Nota: path pode ser usado para definir o título da página)
grip_class : Use uma classe Grip personalizada

render_app

Renderiza a aplicação criada por create_app e retorna o HTML que normalmente apareceria ao visitar aquela rota.

 render_app ( app , route = '/' )

app : O aplicativo Flask para renderizar
route : A rota a ser renderizada, '/' por padrão

render_content

Renderiza o texto de marcação especificado sem armazenamento em cache.

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

text : O texto Markdown a ser renderizado
user_content : se deve renderizar um documento como conteúdo do usuário, como comentários ou problemas do usuário
context : o contexto do projeto a ser usado quando user_content for verdadeiro, que assume a forma de username/project
username : o usuário a ser autenticado no GitHub para estender o limite da API
password : a senha para autenticação no GitHub para estender o limite da API
render_offline : se deve renderizar localmente usando Python-Markdown (Nota: este é um trabalho em andamento)
api_url : um URL base diferente para a API do github, por exemplo, o de uma instância do Github Enterprise. Isso é necessário quando não estiver usando o renderizador offline.
title : o título da página, derivado do path por padrão

render_page

Renderiza a marcação do caminho ou texto especificado, sem armazenamento em cache, e retorna uma página HTML semelhante à visualização Leiame do 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 : O caminho a ser usado para o título da página, renderizando 'README.md' se Nenhum
user_content : se deve renderizar um documento como conteúdo do usuário, como comentários ou problemas do usuário
context : o contexto do projeto a ser usado quando user_content for verdadeiro, que assume a forma de username/project
username : o usuário a ser autenticado no GitHub para estender o limite da API
password : a senha para autenticação no GitHub para estender o limite da API
render_offline : se deve renderizar offline usando Python-Markdown (Nota: este é um trabalho em andamento)
render_wide : Se deve renderizar uma página larga, False por padrão (isso não tem efeito quando usado com user_content )
render_inline : Se os estilos devem ser incorporados no arquivo HTML
api_url : um URL base diferente para a API do github, por exemplo, o de uma instância do Github Enterprise. O padrão é a API pública https://api.github.com.
title : o título da página, derivado do path por padrão
text : uma string ou fluxo de texto Markdown para renderizar em vez de ser carregado do path (Nota: path pode ser usado para definir o título da página)
quiet : não imprime no terminal
theme : Tema para visualizar o arquivo markdown (modo claro ou modo escuro). Opções válidas ("claro", "escuro"). Padrão: "leve".
grip_class : Use uma classe Grip personalizada

limpar_cache

Limpa os estilos e ativos armazenados em cache.

 clear_cache ( grip_class = None )

principal

Executa o Grip com os argumentos especificados.

 main ( argv = None , force_utf8 = True )

argv : os argumentos para executar, sys.argv[1:] por padrão
force_utf8 : define a codificação padrão como utf-8 na instância atual do Python. Isso não tem efeito no Python 3, pois o Unicode é tratado por padrão

Aulas

classe Grip (Frasco)

Um aplicativo Flask que pode servir um arquivo ou diretório contendo um 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_padrão

Retorna o renderizador padrão usando a configuração atual. Isso só será usado se o renderizador estiver definido como None no construtor.

 Grip . default_renderer ()

default_asset_manager

Retorna o gerenciador de ativos padrão usando a configuração atual. Isso só será usado se asset_manager estiver definido como None no construtor.

 Grip . default_asset_manager ()

add_content_types

Adiciona os tipos de conteúdo application/x-font-woff e application/octet-stream se eles estiverem ausentes. Substitua para adicionar tipos de conteúdo adicionais na inicialização.

 Grip . add_content_types ()

limpar_cache

Limpa os ativos baixados.

 Grip . clear_cache ()

renderizar

Renderiza a aplicação e retorna o unicode HTML que normalmente apareceria ao visitar no navegador.

 Grip . render ( route = None )

route : A rota a ser renderizada, / por padrão

correr

Inicia um servidor para renderizar o README. Isso chama Flask.run internamente.

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

host : O nome do host para escutar. Defina como '0.0.0.0' para que o servidor também esteja disponível externamente, 'localhost' por padrão
port : A porta do servidor web. O padrão é 6419
debug : se fornecido, habilite ou desabilite o modo de depuração. Consulte Flask.debug.
use_reloader : O servidor deve reiniciar automaticamente o processo python se os módulos forem alterados? False por padrão, a menos que a configuração DEBUG_GRIP seja especificada.
open_browser : Abre o navegador no endereço quando o servidor inicia

classe JáRunningError(RuntimeError)

Gerado quando Grip.run é chamado enquanto o servidor já está em execução.

 AlreadyRunningError ()

classe ReadmeNotFoundError(NotFoundError ou IOError)

Gerado quando o Leiame especificado não foi encontrado.

 ReadmeNotFoundError ( path = None , message = None )

classe ReadmeAssetManager(objeto)

Gerencia os recursos de estilo e fonte renderizados com páginas Leiame. Esta é uma classe base abstrata.

 ReadmeAssetManager ( cache_path , style_urls = None )

classe GitHubAssetManager(ReadmeAssetManager)

Gerencia os recursos de estilo e fonte renderizados com páginas Leiame. Defina cache_path como None para desabilitar o cache.

classe ReadmeReader(objeto)

Lê o conteúdo Leiame de um subcaminho de URL. Esta é uma classe base abstrata.

 ReadmeReader ()

classe DirectoryReader(ReadmeReader)

Lê arquivos Leiame de subcaminhos de URL.

 DirectoryReader ( path = None , silent = False )

classe TextReader(ReadmeReader)

Lê o conteúdo Leiame da string unicode fornecida.

 TextReader ( text , display_filename = None )

classe StdinReader(TextReader)

Lê o texto Leiame do STDIN.

 StdinReader ( display_filename = None )

classe ReadmeRenderer (objeto)

Renderiza o Leiame. Esta é uma classe base abstrata.

 ReadmeRenderer ( user_content = None , context = None )

classe GitHubRenderer(ReadmeRenderer)

Renderiza o Leiame especificado usando a API GitHub Markdown.

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

classe OfflineRenderer(ReadmeRenderer)

Renderiza o Leiame especificado localmente usando Python puro. Nota: Este é atualmente um recurso incompleto.

 OfflineRenderer ( user_content = None , context = None )

Constantes

SUPPORTED_TITLES

Os títulos de arquivos Markdown comuns no GitHub.

 SUPPORTED_TITLES = [ 'README' , 'Home' ]

filename : O arquivo UTF-8 a ser lido.

SUPPORTED_EXTENSIONS

As extensões suportadas, conforme definido pelo GitHub.

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

DEFAULT_FILENAMES

Esta constante contém os nomes que o Grip procura quando nenhum arquivo é fornecido.

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

DEFAULT_FILENAME

Esta constante contém o nome do arquivo Leiame padrão, a saber:

 DEFAULT_FILENAME = DEFAULT_FILENAMES [ 0 ]  # README.md

DEFAULT_GRIPHOME

Esta constante aponta para o valor padrão se a variável de ambiente GRIPHOME não for especificada.

 DEFAULT_GRIPHOME = '~/.grip'

DEFAULT_GRIPURL

A URL padrão do servidor Grip e todos os seus ativos:

 DEFAULT_GRIPURL = '/__/grip'

DEFAULT_API_URL

O valor app_url padrão:

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

Teste

Instale o pacote e teste os requisitos:

$ pip install -e .[tests]

Execute testes com pytest:

$ pytest

Ou para executar novamente os testes conforme você faz alterações, use pytest-watch:

$ ptw

Testes de suposições externas

Se você estiver enfrentando problemas com o Grip, é provável que uma suposição feita sobre a API do GitHub tenha sido quebrada. Para verificar isso, execute:

$ pytest -m assumption

Como as suposições externas dependem de uma conexão com a Internet, você pode ignorá-las ao desenvolver localmente. Aperte ainda mais o ciclo parando na primeira falha com -x :

$ pytest -xm " not assumption "

Ou com pytest-watch:

$ ptw -- -xm " not assumption "

Contribuindo

Verifique os problemas em aberto ou abra um novo problema para iniciar uma discussão sobre sua ideia de recurso ou o bug que você encontrou
Bifurque o repositório e faça suas alterações
Abra uma nova solicitação pull

Se o seu PR está esperando há algum tempo, sinta-se à vontade para me enviar um ping no Twitter.

Usa este software com frequência? ?

Expandir

grip

Grip – Visualização instantânea do Leiame do GitHub

Motivação

Instalação

Uso

Acesso

Pontas

Crie um espelho local de um Wiki do Github

Gere documentação HTML a partir de uma coleção de arquivos README vinculados

Configuração

Variáveis ​​de ambiente

Avançado

API

Documentação

servir

exportar

criar_app

render_app

render_content

render_page

limpar_cache

principal

Aulas

classe Grip (Frasco)

renderizador_padrão

default_asset_manager

add_content_types

limpar_cache

renderizar

correr

classe JáRunningError(RuntimeError)

classe ReadmeNotFoundError(NotFoundError ou IOError)

classe ReadmeAssetManager(objeto)

classe GitHubAssetManager(ReadmeAssetManager)

classe ReadmeReader(objeto)

classe DirectoryReader(ReadmeReader)

classe TextReader(ReadmeReader)

classe StdinReader(TextReader)

classe ReadmeRenderer (objeto)

classe GitHubRenderer(ReadmeRenderer)

classe OfflineRenderer(ReadmeRenderer)

Constantes

SUPPORTED_TITLES

SUPPORTED_EXTENSIONS

DEFAULT_FILENAMES

DEFAULT_FILENAME

DEFAULT_GRIPHOME

DEFAULT_GRIPURL

DEFAULT_API_URL

Teste

Testes de suposições externas

Contribuindo

Variáveis de ambiente