grip Télécharger - grip Télécharger le code source

Grip - Aperçu instantané GitHub Readme

Restituez les fichiers Lisez-moi locaux avant de les envoyer à GitHub.

Grip est une application serveur de ligne de commande écrite en Python qui utilise l'API de démarque GitHub pour afficher un fichier lisez-moi local. Les styles et le rendu proviennent directement de GitHub, vous saurez donc exactement à quoi cela ressemblera. Les modifications que vous apportez au fichier Readme seront instantanément reflétées dans le navigateur sans nécessiter une actualisation de la page.

Motivation

Parfois, vous souhaitez simplement voir le résultat exact du fichier Lisez-moi avant de vous engager et de le transmettre à GitHub.

Surtout lors du développement basé sur Readme.

Installation

Pour installer le grip, il suffit de :

$ pip install grip

Sous OS X, vous pouvez également installer avec Homebrew :

$ brew install grip

Usage

Pour afficher le readme d'un dépôt :

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

Ouvrez maintenant un navigateur et visitez http://localhost:6419. Ou exécutez avec -b et Grip ouvrira un nouvel onglet de navigateur pour vous.

Vous pouvez également spécifier un port :

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

Ou un fichier explicite :

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

Alternativement, vous pouvez simplement exécuter grip et visiter localhost:6419/AUTHORS.md puisque grip prend en charge les URL relatives.

Vous pouvez combiner les exemples précédents. Ou spécifiez un nom d'hôte au lieu d'un port. Ou fournissez les deux.

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

Vous pouvez même contourner le serveur et exporter vers un seul fichier HTML, avec tous les styles et ressources intégrés :

$ grip --export
Exporting to README.html

Contrôlez le nom de la sortie avec le deuxième argument :

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

Si vous exportez un grand nombre de fichiers, vous pouvez empêcher l'intégration des styles pour économiser de l'espace avec --no-inline :

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

La lecture et l'écriture depuis stdin et stdout sont également prises en charge, vous permettant d'utiliser Grip avec d'autres programmes :

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

$ grip AUTHORS.md --export - | bcat

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

Cela vous permet de tester rapidement à quoi ressemblent les choses en saisissant Markdown directement dans votre terminal :

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

Remarque : ^D signifie Ctrl+D , qui fonctionne sous Linux et OS X. Sous Windows, vous devrez utiliser Ctrl+Z .

Le rendu sous forme de contenu utilisateur, comme les commentaires et les problèmes, est également pris en charge, avec un contexte de référentiel facultatif pour les liens vers les problèmes :

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

Pour plus de détails et des options supplémentaires, consultez l'aide :

$ grip -h

Accéder

Grip s'efforce d'être aussi proche que possible de GitHub. Pour ce faire, grip utilise l'API Markdown de GitHub afin que les modifications apportées à leur moteur de rendu soient reflétées immédiatement sans que vous ayez à mettre à niveau grip. Cependant, à cause de cela, vous risquez d'atteindre la limite de taux horaire de l'API. Si cela se produit, grip offre un moyen d'accéder à l'API en utilisant vos informations d'identification pour débloquer une limite de débit beaucoup plus élevée.

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

Ou utilisez un jeton d'accès personnel avec une portée vide (notez qu'un jeton est requis si votre compte GitHub est configuré avec une authentification à deux facteurs) :

$ grip --pass < token >

Vous pouvez conserver ces options dans votre configuration locale. Pour des raisons de sécurité, il est fortement recommandé d' utiliser un jeton d'accès plutôt qu'un mot de passe . (Vous pouvez également protéger votre mot de passe en configurant Grip pour récupérer votre mot de passe auprès d'un gestionnaire de mots de passe.)

Il existe également une branche de travail en cours pour fournir un rendu hors ligne . Une fois que cela ressemblera plus précisément à GitHub, il sera exposé dans la CLI et sera finalement utilisé comme moteur de secours transparent lorsque l'API n'est pas accessible.

Grip accède toujours à GitHub via HTTPS, afin que votre README et vos informations d'identification soient protégés.

Conseils

Voici comment d'autres membres de la communauté utilisent Grip.

Envie de partager le vôtre ? Dites bonjour @joeyespo ou soumettez une pull request.

Créer un miroir local d'un wiki Github

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

Par Josué Gourneau.

Générer une documentation HTML à partir d'une collection de fichiers README liés

Entrez dans le répertoire :

$ cd YOUR_DIR
$ export GRIPURL= $( pwd )

Incluez tous les actifs en définissant la variable de configuration CACHE_DIRECTORY :
> ~/.grip/settings.py">
```
$ echo " CACHE_DIRECTORY = ' $( pwd ) /assets' " >> ~ /.grip/settings.py
```

Exportez tous vos fichiers Markdown avec Grip et remplacez les chemins absolus des ressources par des chemins relatifs :

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

Vous pouvez éventuellement compresser l'ensemble des fichiers HTML en docs.tgz avec :

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

Vous recherchez une solution multiplateforme ? Voici un script Python équivalent.

Par Matthew R. Tanudjaja.

Configuration

Pour personnaliser Grip, créez ~/.grip/settings.py , puis ajoutez une ou plusieurs des variables suivantes :

HOST : L'hôte à utiliser lorsqu'il n'est pas fourni comme argument CLI, localhost par défaut
PORT : Le port à utiliser lorsqu'il n'est pas fourni en argument CLI, 6419 par défaut
DEBUG : s'il faut utiliser le débogueur de Flask lorsqu'une erreur se produit, False par défaut
DEBUG_GRIP : Imprime des informations étendues lorsqu'une erreur se produit, False par défaut
API_URL : URL de base de l'API github, par exemple celle d'une instance Github Enterprise. https://api.github.com par défaut
CACHE_DIRECTORY : Le répertoire, relatif à ~/.grip , dans lequel placer les actifs mis en cache (cela est exécuté via le filtre suivant : CACHE_DIRECTORY.format(version=__version__) ), 'cache-{version}' par défaut
AUTOREFRESH : s'il faut actualiser automatiquement le contenu Readme lorsque le fichier change, True par défaut
QUIET : Ne pas imprimer les informations étendues, False par défaut
STYLE_URLS : URL supplémentaires qui seront ajoutées à la page rendue, [] par défaut
USERNAME : Le nom d'utilisateur à utiliser lorsqu'il n'est pas fourni comme argument CLI, None par défaut
PASSWORD : Le mot de passe ou le jeton d'accès personnel à utiliser lorsqu'il n'est pas fourni comme argument CLI ( Veuillez ne pas enregistrer vos mots de passe ici. Utilisez plutôt un jeton d'accès ou déposez ce code, récupérez votre mot de passe dans un gestionnaire de mots de passe), None par défaut

Notez qu'il s'agit d'un fichier Python. Si vous voyez des erreurs 'X' is not defined , vous avez peut-être oublié certaines citations. Par exemple:

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

Variables d'environnement

GRIPHOME : Spécifiez un autre emplacement settings.py , ~/.grip par défaut
GRIPURL : L'URL du serveur Grip, /__/grip par défaut

Avancé

Ce fichier est un script Python normal, vous pouvez donc ajouter une configuration plus avancée.

Par exemple, pour lire un paramètre de l'environnement et fournir une valeur par défaut lorsqu'il n'est pas défini :

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

API

Vous pouvez accéder à l'API directement avec Python, en l'utilisant dans vos propres projets :

 from grip import serve

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

Exécutez main directement :

 from grip import main

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

Ou accédez à l'application Flask sous-jacente pour encore plus de flexibilité :

 from grip import create_app

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

Documentation

servir

Exécute un serveur local et restitue le fichier Lisezmoi situé dans path lorsqu'il est visité dans le navigateur.

 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 : Le nom du fichier à restituer, ou le répertoire contenant votre fichier Lisezmoi, par défaut le répertoire de travail actuel
host : L'hôte sur lequel écouter, par défaut sur la variable de configuration HOST
port : Le port sur lequel écouter, par défaut la variable de configuration PORT
user_content : s'il faut restituer un document sous forme de contenu utilisateur, comme des commentaires ou des problèmes d'utilisateur.
context : Le contexte du projet à utiliser lorsque user_content est vrai, qui prend la forme d' username/project
username : L'utilisateur à authentifier auprès de GitHub pour étendre la limite de l'API
password : Le mot de passe pour s'authentifier auprès de GitHub pour étendre la limite de l'API
render_offline : s'il faut effectuer le rendu localement à l'aide de Python-Markdown (Remarque : il s'agit d'un travail en cours)
render_wide : s'il faut afficher une page large, False par défaut (cela n'a aucun effet lorsqu'il est utilisé avec user_content )
render_inline : s'il faut intégrer les styles dans le fichier HTML
api_url : Une URL de base différente pour l'API github, par exemple celle d'une instance Github Enterprise. La valeur par défaut est l'API publique https://api.github.com.
title : Le titre de la page, dérivé du path par défaut
autorefresh : met automatiquement à jour le contenu rendu lorsque le fichier Readme change, True par défaut
browser : Ouvre un onglet dans le navigateur après le démarrage du serveur., False par défaut
grip_class : Utiliser une classe Grip personnalisée

exporter

Écrit le fichier Lisezmoi spécifié dans un fichier HTML avec des styles et des ressources intégrés.

 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 : Le nom du fichier à restituer, ou le répertoire contenant votre fichier Readme, par défaut le répertoire de travail actuel
user_content : s'il faut restituer un document sous forme de contenu utilisateur, comme des commentaires ou des problèmes d'utilisateur.
context : Le contexte du projet à utiliser lorsque user_content est vrai, qui prend la forme d' username/project
username : L'utilisateur à authentifier auprès de GitHub pour étendre la limite de l'API
password : Le mot de passe pour s'authentifier auprès de GitHub pour étendre la limite de l'API
render_offline : s'il faut effectuer le rendu localement à l'aide de Python-Markdown (Remarque : il s'agit d'un travail en cours)
render_wide : s'il faut afficher une page large, False par défaut (cela n'a aucun effet lorsqu'il est utilisé avec user_content )
render_inline : s'il faut intégrer les styles dans le fichier HTML (Remarque : contrairement aux autres fonctions API, la valeur par défaut est True )
out_filename : Le nom du fichier dans lequel écrire, .html par défaut
api_url : Une URL de base différente pour l'API github, par exemple celle d'une instance Github Enterprise. La valeur par défaut est l'API publique https://api.github.com.
title : Le titre de la page, dérivé du path par défaut
quiet : Ne pas imprimer sur le terminal
theme : Thème pour afficher le fichier markdown (mode clair ou mode sombre). Options valides ("clair", "sombre"). Par défaut : "léger".
grip_class : Utiliser une classe Grip personnalisée

créer_app

Crée une application Flask que vous pouvez utiliser pour restituer et servir les fichiers Lisezmoi. Il s'agit de la même application utilisée par serve et export et initialise le cache, en utilisant les styles mis en cache lorsqu'ils sont 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 : Le nom du fichier à restituer, ou le répertoire contenant votre fichier Lisezmoi, par défaut le répertoire de travail actuel
user_content : s'il faut restituer un document sous forme de contenu utilisateur, comme des commentaires ou des problèmes d'utilisateur.
context : Le contexte du projet à utiliser lorsque user_content est vrai, qui prend la forme d' username/project
username : L'utilisateur à authentifier auprès de GitHub pour étendre la limite de l'API
password : Le mot de passe pour s'authentifier auprès de GitHub pour étendre la limite de l'API
render_offline : s'il faut effectuer le rendu localement à l'aide de Python-Markdown (Remarque : il s'agit d'un travail en cours)
render_wide : s'il faut afficher une page large, False par défaut (cela n'a aucun effet lorsqu'il est utilisé avec user_content )
render_inline : s'il faut intégrer les styles dans le fichier HTML
api_url : Une URL de base différente pour l'API github, par exemple celle d'une instance Github Enterprise. La valeur par défaut est l'API publique https://api.github.com.
title : Le titre de la page, dérivé du path par défaut
text : Une chaîne ou un flux de texte Markdown à restituer au lieu d'être chargé à partir du path (Remarque : path peut être utilisé pour définir le titre de la page)
grip_class : Utiliser une classe Grip personnalisée

rendu_app

Rend l'application créée par create_app et renvoie le code HTML qui apparaîtrait normalement lors de la visite de cet itinéraire.

 render_app ( app , route = '/' )

app : L'application Flask à rendre
route : La route à restituer, '/' par défaut

rendu_content

Rend le texte de démarque spécifié sans mise en cache.

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

text : Le texte Markdown à restituer
user_content : s'il faut restituer un document sous forme de contenu utilisateur, comme des commentaires ou des problèmes d'utilisateur.
context : Le contexte du projet à utiliser lorsque user_content est vrai, qui prend la forme d' username/project
username : L'utilisateur à authentifier auprès de GitHub pour étendre la limite de l'API
password : Le mot de passe pour s'authentifier auprès de GitHub pour étendre la limite de l'API
render_offline : s'il faut effectuer le rendu localement à l'aide de Python-Markdown (Remarque : il s'agit d'un travail en cours)
api_url : Une URL de base différente pour l'API github, par exemple celle d'une instance Github Enterprise. Ceci est requis lorsque vous n'utilisez pas le moteur de rendu hors ligne.
title : Le titre de la page, dérivé du path par défaut

page_de rendu

Rend la démarque à partir du chemin ou du texte spécifié, sans mise en cache, et renvoie une page HTML qui ressemble à la vue Readme 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 : Le chemin à utiliser pour le titre de la page, affichant 'README.md' si aucun
user_content : s'il faut restituer un document sous forme de contenu utilisateur, comme des commentaires ou des problèmes d'utilisateur.
context : Le contexte du projet à utiliser lorsque user_content est vrai, qui prend la forme d' username/project
username : L'utilisateur à authentifier auprès de GitHub pour étendre la limite de l'API
password : Le mot de passe pour s'authentifier auprès de GitHub pour étendre la limite de l'API
render_offline : s'il faut effectuer un rendu hors ligne à l'aide de Python-Markdown (Remarque : il s'agit d'un travail en cours)
render_wide : s'il faut afficher une page large, False par défaut (cela n'a aucun effet lorsqu'il est utilisé avec user_content )
render_inline : s'il faut intégrer les styles dans le fichier HTML
api_url : Une URL de base différente pour l'API github, par exemple celle d'une instance Github Enterprise. La valeur par défaut est l'API publique https://api.github.com.
title : Le titre de la page, dérivé du path par défaut
text : Une chaîne ou un flux de texte Markdown à restituer au lieu d'être chargé à partir du path (Remarque : path peut être utilisé pour définir le titre de la page)
quiet : Ne pas imprimer sur le terminal
theme : Thème pour afficher le fichier markdown (mode clair ou mode sombre). Options valides ("clair", "sombre"). Par défaut : "léger".
grip_class : Utiliser une classe Grip personnalisée

clear_cache

Efface les styles et les actifs mis en cache.

 clear_cache ( grip_class = None )

principal

Exécute Grip avec les arguments spécifiés.

 main ( argv = None , force_utf8 = True )

argv : Les arguments avec lesquels exécuter, sys.argv[1:] par défaut
force_utf8 : définit le codage par défaut sur utf-8 dans l'instance Python actuelle. Cela n'a aucun effet sur Python 3 puisque Unicode est géré par défaut

Cours

classe Grip (Flacon)

Une application Flask qui peut servir un fichier ou un répertoire contenant un 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 )

rendu_par défaut

Renvoie le moteur de rendu par défaut en utilisant la configuration actuelle. Ceci n'est utilisé que si le moteur de rendu est défini sur Aucun dans le constructeur.

 Grip . default_renderer ()

default_asset_manager

Renvoie le gestionnaire d'actifs par défaut en utilisant la configuration actuelle. Ceci n'est utilisé que si Asset_manager est défini sur None dans le constructeur.

 Grip . default_asset_manager ()

add_content_types

Ajoute les types de contenu application/x-font-woff et application/octet-stream s'ils sont manquants. Remplacez pour ajouter des types de contenu supplémentaires lors de l’initialisation.

 Grip . add_content_types ()

clear_cache

Efface les ressources téléchargées.

 Grip . clear_cache ()

rendre

Rend l'application et renvoie le HTML Unicode qui apparaîtrait normalement lors de la visite dans le navigateur.

 Grip . render ( route = None )

route : La route à restituer, / par défaut

courir

Démarre un serveur pour afficher le fichier README. Cela appelle Flask.run en interne.

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

host : Le nom d'hôte sur lequel écouter. Réglez-le sur '0.0.0.0' pour que le serveur soit également disponible en externe, 'localhost' par défaut
port : Le port du serveur Web. La valeur par défaut est 6419
debug : si indiqué, activez ou désactivez le mode débogage. Voir Flask.debug.
use_reloader : le serveur doit-il redémarrer automatiquement le processus python si les modules ont été modifiés ? False par défaut, sauf si le paramètre DEBUG_GRIP est spécifié.
open_browser : Ouvre le navigateur à l'adresse au démarrage du serveur

classe DéjàRunningError(RuntimeError)

Déclenché lorsque Grip.run est appelé alors que le serveur est déjà en cours d'exécution.

 AlreadyRunningError ()

classe ReadmeNotFoundError (NotFoundError ou IOError)

Déclenché lorsque le fichier Readme spécifié est introuvable.

 ReadmeNotFoundError ( path = None , message = None )

classe ReadmeAssetManager (objet)

Gère les ressources de style et de police rendues avec les pages Lisezmoi. Il s'agit d'une classe de base abstraite.

 ReadmeAssetManager ( cache_path , style_urls = None )

classe GitHubAssetManager (ReadmeAssetManager)

Gère les ressources de style et de police rendues avec les pages Lisezmoi. Définissez cache_path sur None pour désactiver la mise en cache.

classe ReadmeReader (objet)

Lit le contenu Readme à partir d'un sous-chemin d'URL. Il s'agit d'une classe de base abstraite.

 ReadmeReader ()

classe DirectoryReader (ReadmeReader)

Lit les fichiers Lisezmoi à partir des sous-chemins d'URL.

 DirectoryReader ( path = None , silent = False )

classe TextReader (ReadmeReader)

Lit le contenu Readme à partir de la chaîne Unicode fournie.

 TextReader ( text , display_filename = None )

classe StdinReader (TextReader)

Lit le texte Readme de STDIN.

 StdinReader ( display_filename = None )

classe ReadmeRenderer (objet)

Affiche le fichier Readme. Il s'agit d'une classe de base abstraite.

 ReadmeRenderer ( user_content = None , context = None )

classe GitHubRenderer (ReadmeRenderer)

Renvoie le fichier Readme spécifié à l'aide de l'API GitHub Markdown.

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

classe OfflineRenderer (ReadmeRenderer)

Renvoie le fichier Readme spécifié localement en utilisant du Python pur. Remarque : Il s'agit actuellement d'une fonctionnalité incomplète.

 OfflineRenderer ( user_content = None , context = None )

Constantes

SUPPORTED_TITLES

Les titres de fichiers Markdown courants sur GitHub.

 SUPPORTED_TITLES = [ 'README' , 'Home' ]

filename : Le fichier UTF-8 à lire.

SUPPORTED_EXTENSIONS

Les extensions prises en charge, telles que définies par GitHub.

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

DEFAULT_FILENAMES

Cette constante contient les noms que Grip recherche lorsqu'aucun fichier n'est fourni.

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

DEFAULT_FILENAME

Cette constante contient le nom du fichier Lisezmoi par défaut, à savoir :

 DEFAULT_FILENAME = DEFAULT_FILENAMES [ 0 ]  # README.md

DEFAULT_GRIPHOME

Cette constante pointe vers la valeur par défaut si la variable d'environnement GRIPHOME n'est pas spécifiée.

 DEFAULT_GRIPHOME = '~/.grip'

DEFAULT_GRIPURL

L'URL par défaut du serveur Grip et de tous ses actifs :

 DEFAULT_GRIPURL = '/__/grip'

DEFAULT_API_URL

La valeur app_url par défaut :

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

Essai

Installez le package et testez les exigences :

$ pip install -e .[tests]

Exécutez des tests avec pytest :

$ pytest

Ou pour réexécuter les tests au fur et à mesure que vous apportez des modifications, utilisez pytest-watch :

$ ptw

Tests d'hypothèses externes

Si vous rencontrez un problème avec Grip, il est probable qu'une hypothèse concernant l'API GitHub ait été brisée. Pour vérifier cela, exécutez :

$ pytest -m assumption

Étant donné que les hypothèses externes reposent sur une connexion Internet, vous souhaiterez peut-être les ignorer lors du développement local. Resserrez encore plus le cycle en vous arrêtant au premier échec avec -x :

$ pytest -xm " not assumption "

Ou avec pytest-watch :

$ ptw -- -xm " not assumption "

Contribuer

Vérifiez les problèmes ouverts ou ouvrez un nouveau problème pour démarrer une discussion autour de votre idée de fonctionnalité ou du bug que vous avez trouvé.
Forkez le référentiel et apportez vos modifications
Ouvrir une nouvelle pull request

Si votre PR attend depuis un moment, n'hésitez pas à me contacter sur Twitter.

Vous utilisez souvent ce logiciel ? ?

Développer