抓地力下载 - 抓地力源代码下载

Grip——GitHub 自述文件即时预览

在发送到 GitHub 之前呈现本地自述文件。

Grip 是一个用 Python 编写的命令行服务器应用程序，它使用 GitHub markdown API 来呈现本地自述文件。样式和渲染直接来自 GitHub，因此您将确切地知道它将如何显示。您对自述文件所做的更改将立即反映在浏览器中，无需刷新页面。

动机

有时您只想在提交并推送到 GitHub 之前查看确切的自述文件结果。

特别是在进行自述文件驱动的开发时。

安装

要安装握把，只需：

$ pip install grip

在 OS X 上，您还可以使用 Homebrew 安装：

$ brew install grip

用法

要呈现存储库的自述文件：

$ 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 使用 GitHub 的 Markdown API，以便立即反映其渲染引擎的更改，而无需您升级grip。但是，因此您可能会达到 API 的每小时速率限制。如果发生这种情况，grip 提供了一种使用您的凭据访问 API 的方法，以解锁更高的速率限制。

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

或者使用范围为空的个人访问令牌（请注意，如果您的 GitHub 帐户设置了双因素身份验证，则需要令牌）：

$ grip --pass < token >

您可以将这些选项保留在本地配置中。出于安全目的，强烈建议您使用访问令牌而不是密码。（您还可以通过配置 Grip 从密码管理器获取密码来保证密码安全。）

还有一个正在进行中的分支来提供离线渲染。一旦它更准确地类似于 GitHub，它将在 CLI 中公开，并最终将用作无法访问 API 时的无缝回退引擎。

Grip 始终通过 HTTPS 访问 GitHub，因此您的 README 和凭据受到保护。

尖端

以下是社区中其他人如何使用 Grip。

想分享你自己的吗？向 @joeyespo 打个招呼或提交拉取请求。

创建 Github Wiki 的本地镜像

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

作者：约书亚·古尔诺

从链接的 README 文件集合生成 HTML 文档

输入目录：

$ cd YOUR_DIR
$ export GRIPURL= $( pwd )

通过设置CACHE_DIRECTORY配置变量来包含所有资源：
> ~/.grip/settings.py">
```
$ echo " CACHE_DIRECTORY = ' $( pwd ) /assets' " >> ~ /.grip/settings.py
```

使用 Grip 导出所有 Markdown 文件，并将绝对资源路径替换为相对路径：

$ 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 脚本。

作者：马修·R·塔努贾贾 (Matthew R. Tanudjaja)

配置

要自定义 Grip，请创建~/.grip/settings.py ，然后添加以下一个或多个变量：

HOST ：未作为 CLI 参数提供时使用的主机，默认为localhost
PORT ：未作为 CLI 参数提供时使用的端口，默认为6419
DEBUG ：发生错误时是否使用Flask的调试器，默认为False
DEBUG_GRIP ：发生错误时打印扩展信息，默认为False
API_URL ：github API 的基本 URL，例如 Github Enterprise 实例的基本 URL。默认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 ：Grip 服务器的 URL，默认为/__/grip

先进的

该文件是一个普通的Python脚本，因此您可以添加更高级的配置。

例如，要从环境中读取设置并在未设置时提供默认值：

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

应用程序编程接口

您可以直接使用 Python 访问 API，在您自己的项目中使用它：

 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

文档

服务

运行本地服务器并在浏览器中访问时呈现位于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 ：要渲染的文件名，或包含自述文件的目录，默认为当前工作目录
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 ：github API 的不同基本 URL，例如 Github Enterprise 实例的基本 URL。默认是公共 API https://api.github.com。
title ：页面标题，默认从path派生
autorefresh ：当Readme文件发生变化时自动更新渲染内容，默认为True
browser : 服务器启动后在浏览器中打开一个选项卡，默认为False
grip_class ：使用自定义 Grip 类

出口

将指定的自述文件写入 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 ：要渲染的文件名，或包含自述文件的目录，默认为当前工作目录
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 ：github API 的不同基本 URL，例如 Github Enterprise 实例的基本 URL。默认是公共 API https://api.github.com。
title ：页面标题，默认从path派生
quiet ：不打印到终端
theme ：查看 Markdown 文件的主题（浅色模式或深色模式）。有效选项（“亮”、“暗”）。默认值：“光”。
grip_class ：使用自定义 Grip 类

创建应用程序

创建一个 Flask 应用程序，可用于渲染和提供自述文件。这与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 ：要渲染的文件名，或包含自述文件的目录，默认为当前工作目录
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 ：github API 的不同基本 URL，例如 Github Enterprise 实例的基本 URL。默认是公共 API https://api.github.com。
title ：页面标题，默认从path派生
text ：要渲染的 Markdown 文本字符串或流，而不是从path加载（注意： path可用于设置页面标题）
grip_class ：使用自定义 Grip 类

渲染应用程序

呈现由create_app创建的应用程序并返回访问该路由时通常出现的 HTML。

 render_app ( app , route = '/' )

app ：要渲染的 Flask 应用程序
route : 渲染的路由，默认为 '/'

渲染内容

渲染指定的 Markdown 文本而不进行缓存。

 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 ：github API 的不同基本 URL，例如 Github Enterprise 实例的基本 URL。当不使用离线渲染器时这是必需的。
title ：页面标题，默认从path派生

渲染页面

从指定路径或文本渲染 markdown，不进行缓存，并返回类似于 GitHub Readme 视图的 HTML 页面。

 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 : 用于页面标题的路径，如果 None 则呈现'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 ：github API 的不同基本 URL，例如 Github Enterprise 实例的基本 URL。默认是公共 API https://api.github.com。
title ：页面标题，默认从path派生
text ：要渲染的 Markdown 文本字符串或流，而不是从path加载（注意： path可用于设置页面标题）
quiet ：不打印到终端
theme ：查看 Markdown 文件的主题（浅色模式或深色模式）。有效选项（“亮”、“暗”）。默认值：“光”。
grip_class ：使用自定义 Grip 类

清除缓存

清除缓存的样式和资源。

 clear_cache ( grip_class = None )

主要的

使用指定参数运行 Grip。

 main ( argv = None , force_utf8 = True )

argv ：运行时使用的参数，默认为sys.argv[1:]
force_utf8 ：将当前Python实例中的默认编码设置为utf-8 。这对 Python 3 没有影响，因为默认情况下会处理 Unicode

课程

握把类（烧瓶）

一个 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 )

默认渲染器

使用当前配置返回默认渲染器。仅当渲染器在构造函数中设置为 None 时才使用。

 Grip . default_renderer ()

默认资产管理器

使用当前配置返回默认资产管理器。仅当 asset_manager 在构造函数中设置为 None 时才使用。

 Grip . default_asset_manager ()

添加内容类型

添加 application/x-font-woff 和 application/octet-stream 内容类型（如果缺少）。覆盖以在初始化时添加其他内容类型。

 Grip . add_content_types ()

清除缓存

清除下载的资源。

 Grip . clear_cache ()

使成为

呈现应用程序并返回在浏览器中访问时通常出现的 HTML unicode。

 Grip . render ( route = None )

route : 渲染的路由， /默认

跑步

启动服务器来呈现自述文件。这会在内部调用 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 进程？除非指定了DEBUG_GRIP设置，否则默认为False 。
open_browser ：服务器启动时打开浏览器到该地址

类已经运行错误（运行时错误）

当服务器已在运行时调用Grip.run时引发。

 AlreadyRunningError ()

类 ReadmeNotFoundError（NotFoundError 或 IOError）

当找不到指定的自述文件时引发。

 ReadmeNotFoundError ( path = None , message = None )

类 ReadmeAssetManager(对象)

管理使用自述文件页面呈现的样式和字体资源。这是一个抽象基类。

 ReadmeAssetManager ( cache_path , style_urls = None )

类 GitHubAssetManager(ReadmeAssetManager)

管理使用自述文件页面呈现的样式和字体资源。将cache_path 设置为None 以禁用缓存。

ReadmeReader 类（对象）

从 URL 子路径读取自述文件内容。这是一个抽象基类。

 ReadmeReader ()

类 DirectoryReader(ReadmeReader)

从 URL 子路径读取自述文件。

 DirectoryReader ( path = None , silent = False )

类 TextReader(ReadmeReader)

从提供的 unicode 字符串中读取自述文件内容。

 TextReader ( text , display_filename = None )

类 StdinReader(TextReader)

从 STDIN 读取自述文件文本。

 StdinReader ( display_filename = None )

类 ReadmeRenderer（对象）

呈现自述文件。这是一个抽象基类。

 ReadmeRenderer ( user_content = None , context = None )

类 GitHubRenderer(ReadmeRenderer)

使用 GitHub Markdown API 呈现指定的自述文件。

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

类 OfflineRenderer(ReadmeRenderer)

使用纯 Python 在本地呈现指定的自述文件。注意：目前这是一个不完整的功能。

 OfflineRenderer ( user_content = None , context = None )

常数

支持的_标题

GitHub 上常见的 Markdown 文件标题。

 SUPPORTED_TITLES = [ 'README' , 'Home' ]

filename ：要读取的 UTF-8 文件。

SUPPORTED_EXTENSIONS 个

支持的扩展，由 GitHub 定义。

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

DEFAULT_FILENAMES

该常量包含未提供文件时 Grip 查找的名称。

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

DEFAULT_FILENAME

该常量包含默认的自述文件名，即：

 DEFAULT_FILENAME = DEFAULT_FILENAMES [ 0 ]  # README.md

DEFAULT_GRIPHOME

如果未指定GRIPHOME环境变量，则此常量指向默认值。

 DEFAULT_GRIPHOME = '~/.grip'

DEFAULT_GRIPURL

Grip 服务器及其所有资产的默认 URL：

 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 时遇到问题，很可能是关于 GitHub API 的假设已被打破。要验证这一点，请运行：

$ pytest -m assumption

由于外部假设依赖于互联网连接，因此在本地开发时您可能需要跳过它们。通过使用-x在第一次失败时停止来进一步收紧循环：

$ pytest -xm " not assumption "

或者使用 pytest-watch：

$ ptw -- -xm " not assumption "

贡献

检查未解决的问题或打开新问题以围绕您的功能想法或您发现的错误开始讨论
分叉存储库并进行更改
打开一个新的拉取请求

如果您的公关已经等待了一段时间，请随时在 Twitter 上联系我。

经常使用这个软件吗？？

展开