Загрузка захвата - Загрузка исходного кода захвата

Grip — мгновенный предварительный просмотр файла Readme на GitHub

Отрисовывайте локальные файлы readme перед отправкой на GitHub.

Grip — это серверное приложение командной строки, написанное на Python, которое использует API уценки GitHub для визуализации локального файла readme. Стили и рендеринг взяты непосредственно с GitHub, поэтому вы точно будете знать, как они будут выглядеть. Изменения, внесенные вами в файл Readme, будут мгновенно отражены в браузере без необходимости обновления страницы.

Мотивация

Иногда вы просто хотите увидеть точный результат readme, прежде чем зафиксировать и отправить его на GitHub.

Особенно при разработке на основе Readme.

Установка

Чтобы установить ручку, просто:

$ pip install grip

В OS X вы также можете установить с помощью Homebrew:

$ brew install grip

Использование

Чтобы отобразить файл readme репозитория:

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

Теперь откройте браузер и посетите http://localhost:6419. Или запустите с -b , и Grip откроет для вас новую вкладку браузера.

Вы также можете указать порт:

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

Или явный файл:

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

В качестве альтернативы вы можете просто запустить grip и посетить localhost:6419/AUTHORS.md, поскольку Grip поддерживает относительные URL-адреса.

Вы можете объединить предыдущие примеры. Или укажите имя хоста вместо порта. Или предоставьте и то, и другое.

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

Вы даже можете обойти сервер и экспортировать в один HTML-файл со всеми встроенными стилями и ресурсами:

$ grip --export
Exporting to README.html

Управляйте выходным именем с помощью второго аргумента:

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

Если вы экспортируете кучу файлов, вы можете запретить встраивание стилей для экономии места с помощью --no-inline :

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

Также поддерживается чтение и запись из stdin и stdout , что позволяет использовать Grip с другими программами:

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

$ grip AUTHORS.md --export - | bcat

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

Это позволяет вам быстро проверить, как все выглядит, введя Markdown прямо в терминале:

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

Примечание. ^D означает Ctrl+D , который работает в Linux и OS X. В Windows вам придется использовать Ctrl+Z .

Также поддерживается рендеринг пользовательского контента, например комментариев и задач , с дополнительным контекстом репозитория для ссылки на задачи:

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

Более подробную информацию и дополнительные возможности смотрите в справке:

$ grip -h

Доступ

Grip стремится быть как можно ближе к GitHub. Для этого Grip использует API Markdown от GitHub, поэтому изменения в их механизме рендеринга отражаются немедленно, не требуя обновления Grip. Однако из-за этого вы можете достичь почасового ограничения API. Если это произойдет, Grip предлагает способ доступа к API, используя ваши учетные данные, чтобы разблокировать гораздо более высокий предел скорости.

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

Или используйте личный токен доступа с пустой областью действия (обратите внимание, что токен необходим , если в вашей учетной записи GitHub настроена двухфакторная аутентификация):

$ grip --pass < token >

Вы можете сохранить эти параметры в своей локальной конфигурации. В целях безопасности настоятельно рекомендуется использовать токен доступа вместо пароля . (Вы также можете сохранить свой пароль в безопасности, настроив Grip на получение пароля из менеджера паролей.)

Также в разработке находится ветка, обеспечивающая автономный рендеринг . Как только это будет более точно напоминать GitHub, оно будет отображаться в CLI и в конечном итоге будет использоваться в качестве резервного механизма на случай, если доступ к API будет невозможен.

Grip всегда обращается к GitHub через HTTPS, поэтому ваш README и учетные данные защищены.

Советы

Вот как другие члены сообщества используют Grip.

Хотите поделиться своим? Передайте привет @joeyespo или отправьте запрос на включение.

Создайте локальное зеркало Github Wiki.

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

Джошуа Гурно.

Создание HTML-документации из коллекции связанных файлов README.

Введите каталог:

$ cd YOUR_DIR
$ export GRIPURL= $( pwd )

Включите все ресурсы, установив переменную конфигурации CACHE_DIRECTORY :
> ~/.grip/settings.py">
```
$ echo " CACHE_DIRECTORY = ' $( pwd ) /assets' " >> ~ /.grip/settings.py
```
Экспортируйте все свои файлы Markdown с помощью Grip и замените абсолютные пути к ресурсам относительными:
```
$ for f in * .md ; do grip --export $f --no-inline ; done
$ for f in * .html ; do sed -i ' ' " s? $GRIPURL /??g " $f ; done
```

При желании вы можете сжать набор HTML-файлов в docs.tgz с помощью:

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

Ищете кроссплатформенное решение? Вот эквивалентный скрипт Python.

Мэтью Р. Тануджаджа.

Конфигурация

Чтобы настроить Grip, создайте ~/.grip/settings.py , затем добавьте одну или несколько из следующих переменных:

HOST : хост, который будет использоваться, если он не указан в качестве аргумента CLI, по умолчанию localhost
PORT : порт, который будет использоваться, если он не указан в качестве аргумента CLI, по умолчанию 6419
DEBUG : использовать ли отладчик Flask при возникновении ошибки, по умолчанию False .
DEBUG_GRIP : печатает расширенную информацию при возникновении ошибки, по умолчанию False .
API_URL : базовый URL-адрес API github, например экземпляра Github Enterprise. https://api.github.com по умолчанию.
CACHE_DIRECTORY : Каталог относительно ~/.grip для размещения кэшированных ресурсов (он проходит через следующий фильтр: CACHE_DIRECTORY.format(version=__version__) ), по умолчанию 'cache-{version}'
AUTOREFRESH : следует ли автоматически обновлять содержимое Readme при изменении файла, по умолчанию True .
QUIET : не печатать расширенную информацию, по умолчанию False .
STYLE_URLS : дополнительные URL-адреса, которые будут добавлены на отображаемую страницу, [] по умолчанию.
USERNAME : имя пользователя, которое будет использоваться, если оно не указано в качестве аргумента CLI, по умолчанию None .
PASSWORD : пароль или личный токен доступа, который будет использоваться, если он не указан в качестве аргумента CLI ( пожалуйста, не сохраняйте здесь свои пароли. Вместо этого используйте токен доступа или добавьте этот код, чтобы получить свой пароль из менеджера паролей). По умолчанию None .

Обратите внимание, что это файл Python. Если вы видите ошибку 'X' is not defined , возможно, вы пропустили некоторые кавычки. Например:

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

Переменные среды

GRIPHOME : укажите альтернативное расположение settings.py , по умолчанию ~/.grip
GRIPURL : URL-адрес сервера Grip, по умолчанию /__/grip

Передовой

Этот файл представляет собой обычный скрипт Python, поэтому вы можете добавить более расширенную конфигурацию.

Например, чтобы прочитать параметр из среды и указать значение по умолчанию, если оно не установлено:

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

API

Вы можете получить доступ к API напрямую с Python, используя его в своих проектах:

 from grip import serve

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

Запустите main напрямую:

 from grip import main

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

Или получите доступ к базовому приложению Flask для еще большей гибкости:

 from grip import create_app

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

Документация

служить

Запускает локальный сервер и отображает файл Readme, расположенный по path при посещении в браузере.

 serve ( path = None , host = None , port = None , user_content = False , context = None , username = None , password = None , render_offline = False , render_wide = False , render_inline = False , api_url = None , title = None , autorefresh = True , browser = False , grip_class = None )

path : имя файла для рендеринга или каталог, содержащий файл Readme, по умолчанию используется текущий рабочий каталог.
host : хост для прослушивания, по умолчанию используется переменная конфигурации HOST.
port : порт для прослушивания, по умолчанию используется переменная конфигурации PORT.
user_content : отображать ли документ как пользовательский контент, например, комментарии пользователя или проблемы.
context : контекст проекта, который будет использоваться, когда user_content имеет значение true, который принимает форму username/project
username : пользователь для аутентификации в GitHub, чтобы расширить лимит API.
password : пароль для аутентификации в GitHub для расширения лимита API.
render_offline : выполнять ли локальный рендеринг с использованием Python-Markdown (Примечание: работа над этим еще ведется)
render_wide : отображать ли широкую страницу, по умолчанию False (это не влияет при использовании с user_content )
render_inline : встраивать ли стили в HTML-файл.
api_url : другой базовый URL-адрес API github, например экземпляра Github Enterprise. По умолчанию используется общедоступный API https://api.github.com.
title : заголовок страницы, полученный из path по умолчанию.
autorefresh : автоматически обновлять отображаемый контент при изменении файла Readme, по умолчанию True .
browser : открыть вкладку в браузере после запуска сервера. По умолчанию False
grip_class : использовать собственный класс Grip.

экспорт

Записывает указанный файл Readme в файл HTML со встроенными стилями и ресурсами.

 export ( path = None , user_content = False , context = None , username = None , password = None , render_offline = False , render_wide = False , render_inline = True , out_filename = None , api_url = None , title = None , quiet = None , theme = 'light' , grip_class = None )

path : имя файла для рендеринга или каталог, содержащий файл Readme, по умолчанию используется текущий рабочий каталог.
user_content : отображать ли документ как пользовательский контент, например, комментарии пользователя или проблемы.
context : контекст проекта, который будет использоваться, когда user_content имеет значение true, который принимает форму username/project
username : пользователь для аутентификации в GitHub, чтобы расширить лимит API.
password : пароль для аутентификации в GitHub для расширения лимита API.
render_offline : выполнять ли локальный рендеринг с использованием Python-Markdown (Примечание: работа над этим еще ведется)
render_wide : отображать ли широкую страницу, по умолчанию False (это не влияет при использовании с user_content )
render_inline : встраивать ли стили в HTML-файл (Примечание: в отличие от других функций API, по умолчанию установлено значение True )
out_filename : имя файла для записи, .html по умолчанию.
api_url : другой базовый URL-адрес API github, например экземпляра Github Enterprise. По умолчанию используется общедоступный API https://api.github.com.
title : заголовок страницы, полученный из path по умолчанию.
quiet : не печатать на терминале
theme : тема для просмотра файла уценки (светлый или темный режим). Допустимые варианты («светлый», «темный»). По умолчанию: «светлый».
grip_class : использовать собственный класс Grip.

create_app

Создает приложение Flask, которое можно использовать для визуализации и обслуживания файлов Readme. Это то же приложение, которое используется для serve и export и инициализирует кеш, используя кэшированные стили, если они доступны.

 create_app ( path = None , user_content = False , context = None , username = None , password = None , render_offline = False , render_wide = False , render_inline = False , api_url = None , title = None , text = None , grip_class = None )

path : имя файла для рендеринга или каталог, содержащий файл Readme, по умолчанию используется текущий рабочий каталог.
user_content : отображать ли документ как пользовательский контент, например, комментарии пользователя или проблемы.
context : контекст проекта, который будет использоваться, когда user_content имеет значение true, который принимает форму username/project
username : пользователь для аутентификации в GitHub, чтобы расширить лимит API.
password : пароль для аутентификации в GitHub для расширения лимита API.
render_offline : выполнять ли локальный рендеринг с использованием Python-Markdown (Примечание: работа над этим еще ведется)
render_wide : отображать ли широкую страницу, по умолчанию False (это не влияет при использовании с user_content )
render_inline : встраивать ли стили в HTML-файл.
api_url : другой базовый URL-адрес API github, например экземпляра Github Enterprise. По умолчанию используется общедоступный API https://api.github.com.
title : заголовок страницы, полученный из path по умолчанию.
text : строка или поток текста Markdown для визуализации вместо загрузки по path (Примечание: path можно использовать для установки заголовка страницы).
grip_class : использовать собственный класс Grip.

render_app

Отображает приложение, созданное с помощью create_app , и возвращает HTML-код, который обычно отображается при посещении этого маршрута.

 render_app ( app , route = '/' )

app : приложение Flask для рендеринга.
route : маршрут для рендеринга, по умолчанию '/'.

render_content

Отображает указанный текст уценки без кэширования.

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

text : Текст Markdown для рендеринга.
user_content : отображать ли документ как пользовательский контент, например, комментарии пользователя или проблемы.
context : контекст проекта, который будет использоваться, когда user_content имеет значение true, который принимает форму username/project
username : пользователь для аутентификации в GitHub, чтобы расширить лимит API.
password : пароль для аутентификации в GitHub для расширения лимита API.
render_offline : выполнять ли локальный рендеринг с использованием Python-Markdown (Примечание: работа над этим еще ведется)
api_url : другой базовый URL-адрес API github, например экземпляра Github Enterprise. Это необходимо, если не используется автономный рендерер.
title : заголовок страницы, полученный из path по умолчанию.

рендер_страница

Отображает уценку по указанному пути или тексту без кэширования и возвращает HTML-страницу, похожую на представление 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 : Путь, используемый для заголовка страницы, отображающий 'README.md' если нет.
user_content : отображать ли документ как пользовательский контент, например, комментарии пользователя или проблемы.
context : контекст проекта, который будет использоваться, когда user_content имеет значение true, который принимает форму username/project
username : пользователь для аутентификации в GitHub, чтобы расширить лимит API.
password : пароль для аутентификации в GitHub для расширения лимита API.
render_offline : выполнять ли рендеринг в автономном режиме с использованием Python-Markdown (Примечание: работа над этим еще ведется)
render_wide : отображать ли широкую страницу, по умолчанию False (это не влияет при использовании с user_content )
render_inline : встраивать ли стили в HTML-файл.
api_url : другой базовый URL-адрес API github, например экземпляра Github Enterprise. По умолчанию используется общедоступный API https://api.github.com.
title : заголовок страницы, полученный из path по умолчанию.
text : строка или поток текста Markdown для визуализации вместо загрузки по path (Примечание: path можно использовать для установки заголовка страницы).
quiet : не печатать на терминале
theme : тема для просмотра файла уценки (светлый или темный режим). Допустимые варианты («светлый», «темный»). По умолчанию: «светлый».
grip_class : использовать собственный класс Grip.

очистить_кэш

Очищает кэшированные стили и ресурсы.

 clear_cache ( grip_class = None )

основной

Запускает Grip с указанными аргументами.

 main ( argv = None , force_utf8 = True )

argv : аргументы для запуска, sys.argv[1:] по умолчанию.
force_utf8 : устанавливает кодировку по умолчанию utf-8 в текущем экземпляре Python. Это не влияет на Python 3, поскольку Unicode обрабатывается по умолчанию.

Классы

класс Grip(Колба)

Приложение Flask, которое может обслуживать файл или каталог, содержащий 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

Возвращает средство рендеринга по умолчанию, используя текущую конфигурацию. Это используется только в том случае, если в конструкторе для средства рендеринга установлено значение None.

 Grip . default_renderer ()

default_asset_manager

Возвращает менеджер активов по умолчанию, используя текущую конфигурацию. Это используется только в том случае, если для параметра assets_manager в конструкторе установлено значение None.

 Grip . default_asset_manager ()

add_content_types

Добавляет типы контента application/x-font-woff и application/octet-stream, если они отсутствуют. Переопределить, чтобы добавить дополнительные типы контента при инициализации.

 Grip . add_content_types ()

очистить_кэш

Очищает загруженные ресурсы.

 Grip . clear_cache ()

оказывать

Отрисовывает приложение и возвращает HTML-код Unicode, который обычно отображается при посещении браузера.

 Grip . render ( route = None )

route : маршрут для рендеринга / по умолчанию.

бегать

Запускает сервер для отображения README. Это вызывает внутренний вызов Flask.run.

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

host : имя хоста для прослушивания. Установите для этого параметра значение '0.0.0.0' чтобы сервер был доступен и извне, по умолчанию 'localhost'
port : порт веб-сервера. По умолчанию 6419
debug : Если задано, включите или отключите режим отладки. См. Flask.debug.
use_reloader : Должен ли сервер автоматически перезапускать процесс Python, если модули были изменены? По умолчанию False если не указан параметр DEBUG_GRIP .
open_browser : открывает браузер по адресу при запуске сервера.

класс AlwaysRunningError (RuntimeError)

Возникает, когда Grip.run вызывается, когда сервер уже запущен.

 AlreadyRunningError ()

класс ReadmeNotFoundError (NotFoundError или IOError)

Возникает, когда указанный файл Readme не найден.

 ReadmeNotFoundError ( path = None , message = None )

класс ReadmeAssetManager (объект)

Управляет ресурсами стиля и шрифта, отображаемыми на страницах Readme. Это абстрактный базовый класс.

 ReadmeAssetManager ( cache_path , style_urls = None )

класс GitHubAssetManager (ReadmeAssetManager)

Управляет ресурсами стиля и шрифта, отображаемыми на страницах Readme. Установите для параметра «cache_path» значение «Нет», чтобы отключить кеширование.

класс ReadmeReader (объект)

Считывает содержимое Readme из подпути URL-адреса. Это абстрактный базовый класс.

 ReadmeReader ()

класс DirectoryReader(ReadmeReader)

Считывает файлы Readme из подпутей URL.

 DirectoryReader ( path = None , silent = False )

класс TextReader(ReadmeReader)

Считывает содержимое Readme из предоставленной строки Юникода.

 TextReader ( text , display_filename = None )

класс StdinReader(TextReader)

Считывает текст Readme из STDIN.

 StdinReader ( display_filename = None )

класс ReadmeRenderer (объект)

Отображает Readme. Это абстрактный базовый класс.

 ReadmeRenderer ( user_content = None , context = None )

класс GitHubRenderer (ReadmeRenderer)

Отображает указанный файл Readme с помощью API GitHub Markdown.

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

класс OfflineRenderer (ReadmeRenderer)

Отображает указанный файл Readme локально, используя чистый Python. Примечание. В настоящее время это неполная функция.

 OfflineRenderer ( user_content = None , context = None )

Константы

ПОДДЕРЖИВАЕМЫЕ_ТИТУЛЫ

Распространенные заголовки файлов Markdown на GitHub.

 SUPPORTED_TITLES = [ 'README' , 'Home' ]

filename : файл UTF-8 для чтения.

ПОДДЕРЖИВАЕМЫЕ_РАСШИРЕНИЯ

Поддерживаемые расширения, как определено GitHub.

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

DEFAULT_FILENAMES

Эта константа содержит имена, которые Grip ищет, когда файл не указан.

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

DEFAULT_FILENAME

Эта константа содержит имя файла Readme по умолчанию, а именно:

 DEFAULT_FILENAME = DEFAULT_FILENAMES [ 0 ]  # README.md

DEFAULT_GRIPHOME

Эта константа указывает на значение по умолчанию, если переменная среды GRIPHOME не указана.

 DEFAULT_GRIPHOME = '~/.grip'

DEFAULT_GRIPURL

URL-адрес по умолчанию сервера Grip и всех его ресурсов:

 DEFAULT_GRIPURL = '/__/grip'

DEFAULT_API_URL

Значение app_url по умолчанию:

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

Тестирование

Установите пакет и проверьте требования:

$ pip install -e .[tests]

Запустите тесты с помощью pytest:

$ pytest

Или чтобы повторно запускать тесты по мере внесения изменений, используйте pytest-watch:

$ ptw

Внешние тесты предположений

Если у вас возникла проблема с Grip, вполне вероятно, что предположение об API GitHub не оправдалось. Чтобы убедиться в этом, запустите:

$ pytest -m assumption

Поскольку внешние предположения зависят от подключения к Интернету, вы можете пропустить их при локальной разработке. Еще больше сократите цикл, остановившись при первой ошибке с помощью -x :

$ pytest -xm " not assumption "

Или с помощью pytest-watch:

$ ptw -- -xm " not assumption "

Содействие

Проверьте открытые проблемы или откройте новую проблему, чтобы начать обсуждение идеи вашей функции или обнаруженной вами ошибки.
Создайте форк репозитория и внесите изменения.
Открыть новый запрос на извлечение

Если ваш пиар уже давно ждет, напишите мне в Твиттере.

Часто используете это программное обеспечение? ?

Расширять