Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 428 lines (305 sloc) 16.056 kB
3fbf767 @joeyespo Use "GitHub" instead of "Github".
authored
1 Grip -- GitHub Readme Instant Preview
9bc5190 @joeyespo Initial commit.
authored
2 =====================================
3
ad20298 @joeyespo Add badges.
authored
4 [![Downloads/month on PyPI](http://img.shields.io/pypi/dm/grip.svg)][pypi]
5 [![Current version on PyPI](http://img.shields.io/pypi/v/grip.svg)][pypi]
6
3fbf767 @joeyespo Use "GitHub" instead of "Github".
authored
7 Render local readme files before sending off to GitHub.
9bc5190 @joeyespo Initial commit.
authored
8
9e9a633 @joeyespo Make Readme 'description' implicit.
authored
9 Grip is a command-line server application written in Python that uses the
3fbf767 @joeyespo Use "GitHub" instead of "Github".
authored
10 [GitHub markdown API][markdown] to render a local readme file. The styles also
11 come directly from GitHub, so you'll know exactly how it will appear.
9bc5190 @joeyespo Initial commit.
authored
12
13
84cb514 @joeyespo README section wording.
authored
14 Motivation
15 ----------
9bc5190 @joeyespo Initial commit.
authored
16
17 Sometimes you just want to see the exact readme
3fbf767 @joeyespo Use "GitHub" instead of "Github".
authored
18 result before committing and pushing to GitHub.
9bc5190 @joeyespo Initial commit.
authored
19
2dc2014 @joeyespo Readme: Add 'Readme-driven development' note.
authored
20 Especially when doing [Readme-driven development][rdd].
21
9bc5190 @joeyespo Initial commit.
authored
22
e4a4df5 @joeyespo Move up installation.
authored
23 Installation
24 ------------
25
26 To install grip, simply:
27
dd751c4 @joeyespo Readme: fences.
authored
28 ```bash
29 $ pip install grip
30 ```
e4a4df5 @joeyespo Move up installation.
authored
31
32
9bc5190 @joeyespo Initial commit.
authored
33 Usage
34 -----
35
6706fdf @joeyespo Readme: simplify 'usage'.
authored
36 To render the readme of a repository:
9bc5190 @joeyespo Initial commit.
authored
37
dd751c4 @joeyespo Readme: fences.
authored
38 ```bash
39 $ cd myrepo
fa7f22f @joeyespo Readme: Add usage examples.
authored
40 $ grip
4a5ee59 @joeyespo Fix #123: Change the default port to 6419.
authored
41 * Running on http://localhost:6419/
dd751c4 @joeyespo Readme: fences.
authored
42 ```
9bc5190 @joeyespo Initial commit.
authored
43
4a5ee59 @joeyespo Fix #123: Change the default port to 6419.
authored
44 Now open a browser and visit [http://localhost:6419](http://localhost:6419/).
8129729 @joeyespo Update README to reflect port argument.
authored
45
fa7f22f @joeyespo Readme: Add usage examples.
authored
46 You can also specify a port:
47
48 ```bash
49 $ grip 80
50 * Running on http://localhost:80/
51 ```
52
53 Or an explicit file:
54
55 ```bash
ed5eb92 @joeyespo Add note about relative URLs, using AUTHORS.md.
authored
56 $ grip AUTHORS.md
4a5ee59 @joeyespo Fix #123: Change the default port to 6419.
authored
57 * Running on http://localhost:6419/
fa7f22f @joeyespo Readme: Add usage examples.
authored
58 ```
59
4a5ee59 @joeyespo Fix #123: Change the default port to 6419.
authored
60 Alternatively, you could just run `grip` and visit [localhost:6419/AUTHORS.md][AUTHORS.md]
ed5eb92 @joeyespo Add note about relative URLs, using AUTHORS.md.
authored
61 since grip supports relative URLs.
62
4453cd3 @joeyespo Readme: Clarify descriptions and examples.
authored
63 You can combine the previous examples. Or specify a hostname instead of a port. Or provide both.
82eb9fb @joeyespo Add note about using both a path and address.
authored
64
65 ```bash
8a90ee4 @joeyespo Add more path and address examples.
authored
66 $ grip AUTHORS.md 80
67 * Running on http://localhost:80/
68 ```
69
70 ```bash
4453cd3 @joeyespo Readme: Clarify descriptions and examples.
authored
71 $ grip CHANGES.md 0.0.0.0
4a5ee59 @joeyespo Fix #123: Change the default port to 6419.
authored
72 * Running on http://0.0.0.0:6419/
4453cd3 @joeyespo Readme: Clarify descriptions and examples.
authored
73 ```
74
75 ```bash
76 $ grip . 0.0.0.0:80
82eb9fb @joeyespo Add note about using both a path and address.
authored
77 * Running on http://0.0.0.0:80/
78 ```
79
2c3cc4b @joeyespo Readme: Add bold for skimmability.
authored
80 You can even bypass the server and **export** to a single HTML file, with all the styles and assets inlined:
4453cd3 @joeyespo Readme: Clarify descriptions and examples.
authored
81
8a90ee4 @joeyespo Add more path and address examples.
authored
82 ```bash
4453cd3 @joeyespo Readme: Clarify descriptions and examples.
authored
83 $ grip --export
84 Exporting to README.html
8a90ee4 @joeyespo Add more path and address examples.
authored
85 ```
86
4453cd3 @joeyespo Readme: Clarify descriptions and examples.
authored
87 Control the output name with the second argument:
1955831 Cleanup Todo s and stuff
iliggio authored
88
89 ```bash
e708d34 @joeyespo Re-order --export argument for clarity.
authored
90 $ grip README.md --export readme.html
d98c4e2 @joeyespo Fix example output and tweak wording.
authored
91 Exporting to readme.html
1955831 Cleanup Todo s and stuff
iliggio authored
92 ```
93
6e0e570 @joeyespo Add piping support:
authored
94 Reading and writing from **stdin** and **stdout** is also supported, allowing you to use Grip with other programs:
95
96 ```bash
97 $ cat README.md | grip -
4a5ee59 @joeyespo Fix #123: Change the default port to 6419.
authored
98 * Running on http://localhost:6419/
6e0e570 @joeyespo Add piping support:
authored
99 ```
100
101 ```bash
e708d34 @joeyespo Re-order --export argument for clarity.
authored
102 $ grip AUTHORS.md --export - | bcat
6e0e570 @joeyespo Add piping support:
authored
103 ```
104
105 ```bash
106 $ cat README.md | grip --export - | less
107 ```
108
d98c4e2 @joeyespo Fix example output and tweak wording.
authored
109 This allows you to quickly test how things look by entering Markdown directly in your terminal:
6e0e570 @joeyespo Add piping support:
authored
110
111 ```bash
112 $ grip -
113 Hello **world**!
3a1a5a3 @joeyespo Readme: Fix #105 by using ^D and adding a note.
authored
114 ^D
4a5ee59 @joeyespo Fix #123: Change the default port to 6419.
authored
115 * Running on http://localhost:6419/
6e0e570 @joeyespo Add piping support:
authored
116 ```
117
3a1a5a3 @joeyespo Readme: Fix #105 by using ^D and adding a note.
authored
118 *Note: `^D` means `Ctrl+D`, which works on Linux and iOS. On Windows you'll have to use `Ctrl+Z`.*
119
2c3cc4b @joeyespo Readme: Add bold for skimmability.
authored
120 **Comment / issue-style GFM** is also supported, with an optional repository context for linking to issues:
fa7f22f @joeyespo Readme: Add usage examples.
authored
121
122 ```bash
123 $ grip --gfm --context=joeyespo/grip
4a5ee59 @joeyespo Fix #123: Change the default port to 6419.
authored
124 * Running on http://localhost:6419/
fa7f22f @joeyespo Readme: Add usage examples.
authored
125 ```
126
5390618 @joeyespo Add --wide option.
authored
127 For more details and additional options, see the help:
fa7f22f @joeyespo Readme: Add usage examples.
authored
128
129 ```bash
130 $ grip -h
131 ```
132
9bc5190 @joeyespo Initial commit.
authored
133
938204a @joeyespo Fix #46: Document the --user / --pass arguments
authored
134 Access
135 ------
136
137 Grip strives to be as close to GitHub as possible. To accomplish this, grip
138 uses [GitHub's Markdown API][markdown] so that changes to their rendering
139 engine are reflected immediately without requiring you to upgrade grip.
140 However, because of this you may hit the API's hourly rate limit. If this
141 happens, grip offers a way to access the API using your credentials
142 to unlock a much higher rate limit.
143
144 ```bash
145 $ grip --user <your-username> --pass <your-password>
146 ```
147
648a0a4 @joeyespo Document using tokens with --pass, add security concern to README, an…
authored
148 Or use a [personal access token][] with an empty scope (note that a token is
149 *required* if your GitHub account is set up with two-factor authentication):
4f91f11 @joeyespo Document the configuration options.
authored
150
6be3ea6 @joeyespo Clarify personal access tokens:
authored
151 ```bash
152 $ grip --pass <token>
153 ```
154
155 You can persist these options [in your local configuration](#configuration).
648a0a4 @joeyespo Document using tokens with --pass, add security concern to README, an…
authored
156 For security purposes, it's highly recommended that you **use an access token
157 over a password**. (You could also keep your password safe by configuring
158 Grip to [grab your password from a password manager][keychain-access].)
f3fbe35 @davejamesmiller Link to create a personal access token in readme
davejamesmiller authored
159
b13d18b @joeyespo README: Refer to the offline rendering branch in the Access section.
authored
160 There's also a [work-in-progress branch][fix-render-offline] to provide
161 **offline rendering**. Once this resembles GitHub more precisely, it'll
162 be exposed in the CLI, and will ultimately be used as a seamless fallback
163 engine for when the API can't be accessed.
164
b4c03f9 @joeyespo Leftover space.
authored
165 Grip always accesses GitHub over HTTPS,
82c506a @joeyespo Tweak the README:
authored
166 so your README and credentials are protected.
b13d18b @joeyespo README: Refer to the offline rendering branch in the Access section.
authored
167
c23eace @joeyespo README cleanup.
authored
168
9435ca6 @joeyespo Add Known Issues section.
authored
169 Known issues
170 ------------
171
172 - [ ] GitHub introduced read-only task lists to all Markdown documents in
173 repositories and wikis [back in April][task-lists], but
82c506a @joeyespo Tweak the README:
authored
174 [the API][markdown] doesn't respect this yet.
9435ca6 @joeyespo Add Known Issues section.
authored
175
176
4f91f11 @joeyespo Document the configuration options.
authored
177 Configuration
178 -------------
179
6f443bb @joeyespo Clarify Configuration section and add an example.
authored
180 To customize Grip, create `~/.grip/settings.py`, then add one or more of the following variables:
4f91f11 @joeyespo Document the configuration options.
authored
181
182 - `HOST`: The host to use when not provided as a CLI argument, `localhost` by default
4a5ee59 @joeyespo Fix #123: Change the default port to 6419.
authored
183 - `PORT`: The port to use when not provided as a CLI argument, `6419` by default
4f91f11 @joeyespo Document the configuration options.
authored
184 - `DEBUG`: Whether to use Flask's debugger when an error happens, `True` by default
185 - `DEBUG_GRIP`: Prints extended information when an error happens, `False` by default
186 - `USERNAME`: The username to use when not provided as a CLI argument, `None` by default
648a0a4 @joeyespo Document using tokens with --pass, add security concern to README, an…
authored
187 - `PASSWORD`: The password or [personal access token][] to use when not provided as a CLI argument (*Please don't save your passwords here.* Instead, use an access token or drop in this code [grab your password from a password manager][keychain-access]), `None` by default
c67f185 @dandavison Update API documentation
dandavison authored
188 - `API_URL`: Base URL for the github API, for example that of a Github Enterprise instance. The default is the public API https://api.github.com.
df91f38 @joeyespo Add `{version}` format argument to `CACHE_DIRECTORY`:
authored
189 - `CACHE_DIRECTORY`: The directory, relative to `~/.grip`, to place cached assets (this gets run through the following filter: `CACHE_DIRECTORY.format(version=__version__)`), `'cache-{version}'` by default
82a1e5d @joeyespo Add URL safeguards in case of conflict:
authored
190 - `CACHE_URL`: The URL to serve cached styles and assets from, in case there's a URL conflict, `'/grip-cache'` by default
191 - `STATIC_URL_PATH`: The URL to serve static assets from, in case there's a URL conflict, `'/grip-static'` by default
d8abb6f @joeyespo Remove leftover STYLE_URLS note.
authored
192 - `STYLE_URLS`: Additional URLs that will be added to the rendered page, `[]` by default
4f91f11 @joeyespo Document the configuration options.
authored
193 - `STYLE_URLS_SOURCE`: The URL to use to locate and download the styles from, `https://github.com/joeyespo/grip` by default
194 - `STYLE_URLS_RE`: The regular expression to use to parse the styles from the source
8940a03 @joeyespo Cache style assets:
authored
195 - `STYLE_ASSET_URLS_RE`: The regular expression to use to parse the assets from the styles
196 - `STYLE_ASSET_URLS_SUB`: Replaces the above regular expression with a local URL, as saved in the cache
97c26e6 @joeyespo Inline assets into styles when exporting.
authored
197 - `STYLE_ASSET_URLS_INLINE`: The regular expression to use when inlining assets into the downloaded style
198 Note that this must include both the original and post-`STYLE_ASSET_URLS_SUB` patterns.
4f91f11 @joeyespo Document the configuration options.
authored
199
6f443bb @joeyespo Clarify Configuration section and add an example.
authored
200 #### Advanced
4f91f11 @joeyespo Document the configuration options.
authored
201
6f443bb @joeyespo Clarify Configuration section and add an example.
authored
202 This file is a normal Python script, so you can add more advanced configuration.
203
204 For example, to read a setting from the environment and provide a default value
205 when it's not set:
206
207 ```python
208 PORT = os.environ.get('GRIP_PORT', 8080)
209 ```
4f91f11 @joeyespo Document the configuration options.
authored
210
211
e387909 @joeyespo Readme: rename 'Python API' section to 'API'.
authored
212 API
213 ---
9bc5190 @joeyespo Initial commit.
authored
214
215 You can access the API directly with Python, using it in your own projects:
216
dd751c4 @joeyespo Readme: fences.
authored
217 ```python
218 from grip import serve
219
8e5253a @joeyespo Remove arguments.
authored
220 serve(port=8080)
a9b8f79 @joeyespo Fix README port typo.
authored
221 * Running on http://localhost:8080/
dd751c4 @joeyespo Readme: fences.
authored
222 ```
9bc5190 @joeyespo Initial commit.
authored
223
e120a9f @joeyespo Update API documentation.
authored
224 Or access the underlying Flask application for even more flexibility:
225
226 ```python
227 from grip import create_app
228
229 grip_app = create_app(gfm=True)
230 # Use in your own app
231 ```
232
233
8eb4d34 @joeyespo Readme: Add documentation section.
authored
234 ### Documentation
235
e120a9f @joeyespo Update API documentation.
authored
236 #### serve
f0611b3 @joeyespo Update API section in README.
authored
237
e120a9f @joeyespo Update API documentation.
authored
238 Runs a local server and renders the Readme file located
239 at `path` when visited in the browser.
f0611b3 @joeyespo Update API section in README.
authored
240
241 ```python
e277a1c @joeyespo Sync README docs with recent additions.
authored
242 serve(path=None, host=None, port=None, gfm=False, context=None, username=None, password=None, render_offline=False, render_wide=False, render_inline=False, api_url=None, title=None)
f0611b3 @joeyespo Update API section in README.
authored
243 ```
244
2f286d0 @joeyespo Fix API documentation.
authored
245 - `path`: The filename to render, or the directory containing your Readme file, defaulting to the current working directory
246 - `host`: The host to listen on, defaulting to the HOST configuration variable
247 - `port`: The port to listen on, defaulting to the PORT configuration variable
f0611b3 @joeyespo Update API section in README.
authored
248 - `gfm`: Whether to render using [GitHub Flavored Markdown][gfm]
249 - `context`: The project context to use when `gfm` is true, which
250 takes the form of `username/project`
251 - `username`: The user to authenticate with GitHub to extend the API limit
252 - `password`: The password to authenticate with GitHub to extend the API limit
515a1e6 @joeyespo Remove --render-offline from release until fixed.
authored
253 - `render_offline`: Whether to render locally using [Python-Markdown][] (Note: this is a work in progress)
76b67ec @joeyespo Remove 'Note' from render_wide docs so the text fits.
authored
254 - `render_wide`: Whether to render a wide page, `False` by default (this has no effect when used with `gfm`)
818f1de @joeyespo Rewrite rendering code to re-use the Flask app, and adjust API accord…
authored
255 - `render_inline`: Whether to inline the styles within the HTML file
e277a1c @joeyespo Sync README docs with recent additions.
authored
256 - `api_url`: A different base URL for the github API, for example that of a Github Enterprise instance. The default is the public API https://api.github.com.
257 - `title`: The page title, derived from `path` by default
f0611b3 @joeyespo Update API section in README.
authored
258
259
e120a9f @joeyespo Update API documentation.
authored
260 #### export
8eb4d34 @joeyespo Readme: Add documentation section.
authored
261
97c26e6 @joeyespo Inline assets into styles when exporting.
authored
262 Writes the specified Readme file to an HTML file with styles and assets inlined.
1fee442 @joeyespo Readme: Add description.
authored
263
8eb4d34 @joeyespo Readme: Add documentation section.
authored
264 ```python
e277a1c @joeyespo Sync README docs with recent additions.
authored
265 export(path=None, gfm=False, context=None, username=None, password=None, render_offline=False, render_wide=False, render_inline=True, out_filename=None, api_url=None, title=None)
e120a9f @joeyespo Update API documentation.
authored
266 ```
267
2f286d0 @joeyespo Fix API documentation.
authored
268 - `path`: The filename to render, or the directory containing your Readme file, defaulting to the current working directory
e120a9f @joeyespo Update API documentation.
authored
269 - `gfm`: Whether to render using [GitHub Flavored Markdown][gfm]
270 - `context`: The project context to use when `gfm` is true, which
271 takes the form of `username/project`
272 - `username`: The user to authenticate with GitHub to extend the API limit
273 - `password`: The password to authenticate with GitHub to extend the API limit
515a1e6 @joeyespo Remove --render-offline from release until fixed.
authored
274 - `render_offline`: Whether to render locally using [Python-Markdown][] (Note: this is a work in progress)
2f286d0 @joeyespo Fix API documentation.
authored
275 - `render_wide`: Whether to render a wide page, `False` by default (this has no effect when used with `gfm`)
818f1de @joeyespo Rewrite rendering code to re-use the Flask app, and adjust API accord…
authored
276 - `render_inline`: Whether to inline the styles within the HTML file (Note: unlike the other API functions, this defaults to `True`)
e120a9f @joeyespo Update API documentation.
authored
277 - `out_filename`: The filename to write to, `<in_filename>.html` by default
e277a1c @joeyespo Sync README docs with recent additions.
authored
278 - `api_url`: A different base URL for the github API, for example that of a Github Enterprise instance. The default is the public API https://api.github.com.
279 - `title`: The page title, derived from `path` by default
e120a9f @joeyespo Update API documentation.
authored
280
281
282 #### create_app
283
284 Creates a Flask application you can use to render and serve the Readme files.
285 This is the same app used by `serve` and `export` and initializes the cache,
286 using the cached styles when available.
287
288 ```python
e277a1c @joeyespo Sync README docs with recent additions.
authored
289 create_app(path=None, gfm=False, context=None, username=None, password=None, render_offline=False, render_wide=False, render_inline=False, api_url=None, title=None, text=None)
8eb4d34 @joeyespo Readme: Add documentation section.
authored
290 ```
291
2f286d0 @joeyespo Fix API documentation.
authored
292 - `path`: The filename to render, or the directory containing your Readme file, defaulting to the current working directory
8eb4d34 @joeyespo Readme: Add documentation section.
authored
293 - `gfm`: Whether to render using [GitHub Flavored Markdown][gfm]
294 - `context`: The project context to use when `gfm` is true, which
295 takes the form of `username/project`
f0611b3 @joeyespo Update API section in README.
authored
296 - `username`: The user to authenticate with GitHub to extend the API limit
297 - `password`: The password to authenticate with GitHub to extend the API limit
515a1e6 @joeyespo Remove --render-offline from release until fixed.
authored
298 - `render_offline`: Whether to render locally using [Python-Markdown][] (Note: this is a work in progress)
76b67ec @joeyespo Remove 'Note' from render_wide docs so the text fits.
authored
299 - `render_wide`: Whether to render a wide page, `False` by default (this has no effect when used with `gfm`)
e120a9f @joeyespo Update API documentation.
authored
300 - `render_inline`: Whether to inline the styles within the HTML file
e277a1c @joeyespo Sync README docs with recent additions.
authored
301 - `api_url`: A different base URL for the github API, for example that of a Github Enterprise instance. The default is the public API https://api.github.com.
302 - `title`: The page title, derived from `path` by default
818f1de @joeyespo Rewrite rendering code to re-use the Flask app, and adjust API accord…
authored
303 - `text`: A string or stream of Markdown text to render instead of being loaded from `path` (Note: `path` can be used to set the page title)
e120a9f @joeyespo Update API documentation.
authored
304
305
306 #### render_app
307
818f1de @joeyespo Rewrite rendering code to re-use the Flask app, and adjust API accord…
authored
308 Renders the application created by `create_app` and returns the HTML that would
309 normally appear when visiting that route.
310
e120a9f @joeyespo Update API documentation.
authored
311 ```python
312 render_app(app, route='/')
313 ```
314
315 - `app`: The Flask application to render
316 - `route`: The route to render, '/' by default
8eb4d34 @joeyespo Readme: Add documentation section.
authored
317
b458663 @joeyespo Readme: Add 'contributing' section.
authored
318
681170f @joeyespo Readme: Document remaining functions.
authored
319 #### render_content
320
e120a9f @joeyespo Update API documentation.
authored
321 Renders the specified markdown text without caching.
681170f @joeyespo Readme: Document remaining functions.
authored
322
323 ```python
e277a1c @joeyespo Sync README docs with recent additions.
authored
324 render_content(text, gfm=False, context=None, username=None, password=None, render_offline=False, api_url=None, title=None)
681170f @joeyespo Readme: Document remaining functions.
authored
325 ```
326
818f1de @joeyespo Rewrite rendering code to re-use the Flask app, and adjust API accord…
authored
327 - `text`: The Markdown text to render
681170f @joeyespo Readme: Document remaining functions.
authored
328 - `gfm`: Whether to render using [GitHub Flavored Markdown][gfm]
329 - `context`: The project context to use when `gfm` is true, which
330 takes the form of `username/project`
f0611b3 @joeyespo Update API section in README.
authored
331 - `username`: The user to authenticate with GitHub to extend the API limit
332 - `password`: The password to authenticate with GitHub to extend the API limit
515a1e6 @joeyespo Remove --render-offline from release until fixed.
authored
333 - `render_offline`: Whether to render locally using [Python-Markdown][] (Note: this is a work in progress)
e277a1c @joeyespo Sync README docs with recent additions.
authored
334 - `api_url`: A different base URL for the github API, for example that of a Github Enterprise instance. This is required when not using the offline renderer.
335 - `title`: The page title, derived from `path` by default
681170f @joeyespo Readme: Document remaining functions.
authored
336
f0611b3 @joeyespo Update API section in README.
authored
337
681170f @joeyespo Readme: Document remaining functions.
authored
338 #### render_page
339
818f1de @joeyespo Rewrite rendering code to re-use the Flask app, and adjust API accord…
authored
340 Renders the markdown from the specified path or text, without caching,
341 and returns an HTML page that resembles the GitHub Readme view.
681170f @joeyespo Readme: Document remaining functions.
authored
342
343 ```python
e277a1c @joeyespo Sync README docs with recent additions.
authored
344 render_page(path=None, gfm=False, context=None, username=None, password=None, render_offline=False, render_wide=False, render_inline=False, api_url=None, title=None, text=None)
681170f @joeyespo Readme: Document remaining functions.
authored
345 ```
346
818f1de @joeyespo Rewrite rendering code to re-use the Flask app, and adjust API accord…
authored
347 - `path`: The path to use for the page title, rendering `'README.md'` if None
681170f @joeyespo Readme: Document remaining functions.
authored
348 - `gfm`: Whether to render using [GitHub Flavored Markdown][gfm]
349 - `context`: The project context to use when `gfm` is true, which
350 takes the form of `username/project`
f0611b3 @joeyespo Update API section in README.
authored
351 - `username`: The user to authenticate with GitHub to extend the API limit
352 - `password`: The password to authenticate with GitHub to extend the API limit
515a1e6 @joeyespo Remove --render-offline from release until fixed.
authored
353 - `render_offline`: Whether to render offline using [Python-Markdown][] (Note: this is a work in progress)
76b67ec @joeyespo Remove 'Note' from render_wide docs so the text fits.
authored
354 - `render_wide`: Whether to render a wide page, `False` by default (this has no effect when used with `gfm`)
818f1de @joeyespo Rewrite rendering code to re-use the Flask app, and adjust API accord…
authored
355 - `render_inline`: Whether to inline the styles within the HTML file
e277a1c @joeyespo Sync README docs with recent additions.
authored
356 - `api_url`: A different base URL for the github API, for example that of a Github Enterprise instance. The default is the public API https://api.github.com.
357 - `title`: The page title, derived from `path` by default
818f1de @joeyespo Rewrite rendering code to re-use the Flask app, and adjust API accord…
authored
358 - `text`: A string or stream of Markdown text to render instead of being loaded from `path` (Note: `path` can be used to set the page title)
f0611b3 @joeyespo Update API section in README.
authored
359
fdb89cc @joeyespo Fix --export and add resolve_readme to the API.
authored
360 #### resolve_readme
361
362 Returns the path if it's a file; otherwise, looks for a compatible README file
363 in the directory specified by path. If path is None, the current working
364 directory is used. If no compatible README can be found, ValueError is raised.
365
366 ```python
818f1de @joeyespo Rewrite rendering code to re-use the Flask app, and adjust API accord…
authored
367 resolve_readme(path=None, force=False)
fdb89cc @joeyespo Fix --export and add resolve_readme to the API.
authored
368 ```
369
370 - `path`: The filename to render, or the directory containing your Readme file, defaulting to the current working directory
818f1de @joeyespo Rewrite rendering code to re-use the Flask app, and adjust API accord…
authored
371 - `force`: Whether to force a result, even when a readme file is not found
fdb89cc @joeyespo Fix --export and add resolve_readme to the API.
authored
372
373
f400895 @joeyespo Add --clear to clear the cache.
authored
374 #### clear_cache
375
f25740b @joeyespo Fix clear_cache docs and add docstring.
authored
376 Clears the cached styles and assets.
f400895 @joeyespo Add --clear to clear the cache.
authored
377
378 ```python
379 clear_cache()
380 ```
381
382
8b2afa4 @joeyespo Extract default filename constants:
authored
383 #### supported_extensions
384
385 The supported extensions, as defined by [GitHub][markdown].
386
387 ```python
388 supported_extensions = ['.md', '.markdown']
389 ```
390
391
648a765 @joeyespo Readme: Document constants.
authored
392 #### default_filenames
393
8b2afa4 @joeyespo Extract default filename constants:
authored
394 This constant contains the names Grip looks for when no file is provided.
648a765 @joeyespo Readme: Document constants.
authored
395
396 ```python
8b2afa4 @joeyespo Extract default filename constants:
authored
397 default_filenames = map(lambda ext: 'README' + ext, supported_extensions)
648a765 @joeyespo Readme: Document constants.
authored
398 ```
399
681170f @joeyespo Readme: Document remaining functions.
authored
400
b458663 @joeyespo Readme: Add 'contributing' section.
authored
401 Contributing
402 ------------
403
404 1. Check the open issues or open a new issue to start a discussion around
405 your feature idea or the bug you found
d44a0bd @joeyespo Remind authors to add themselves to AUTHORS.md.
authored
406 2. Fork the repository, make your changes, and add yourself to [Authors.md][]
b458663 @joeyespo Readme: Add 'contributing' section.
authored
407 3. Send a pull request
408
aa51f4d @joeyespo Add support and contact info.
authored
409 If your PR has been waiting a while, feel free to [ping me on Twitter][twitter].
410
411 Use this software often? Please consider supporting me on
5625e40 @joeyespo Reflect the Gittip rename to Gratipay.
authored
412 <a href="http://gratipay.com/joeyespo" title="Thank you!">
413 <img align="center" style="margin-bottom:1px" src="http://joeyespo.com/images/gratipay-button.png" alt="Gratipay">
aa51f4d @joeyespo Add support and contact info.
authored
414 </a>
415
b458663 @joeyespo Readme: Add 'contributing' section.
authored
416
ad20298 @joeyespo Add badges.
authored
417 [pypi]: http://pypi.python.org/pypi/grip/
643ab19 @joeyespo Readme: reword Github 'markup' to 'markdown'.
authored
418 [markdown]: http://developer.github.com/v3/markdown
c23eace @joeyespo README cleanup.
authored
419 [rdd]: http://tom.preston-werner.com/2010/08/23/readme-driven-development.html
420 [authors.md]: AUTHORS.md
b13d18b @joeyespo README: Refer to the offline rendering branch in the Access section.
authored
421 [fix-render-offline]: http://github.com/joeyespo/grip/tree/fix-render-offline
648a0a4 @joeyespo Document using tokens with --pass, add security concern to README, an…
authored
422 [personal access token]: https://github.com/settings/tokens/new?scopes=
423 [keychain-access]: https://gist.github.com/klmr/3840aa3c12f947e4064c
9435ca6 @joeyespo Add Known Issues section.
authored
424 [task-lists]: https://github.com/blog/1825-task-lists-in-all-markdown-documents
ed5eb92 @joeyespo Add note about relative URLs, using AUTHORS.md.
authored
425 [gfm]: http://github.github.com/github-flavored-markdown
c23eace @joeyespo README cleanup.
authored
426 [python-markdown]: http://github.com/waylan/Python-Markdown
aa51f4d @joeyespo Add support and contact info.
authored
427 [twitter]: http://twitter.com/joeyespo
Something went wrong with that request. Please try again.