grip
grip copied to clipboard
joeyespo
rst support
Is there a way to test locally how .rst (restructured text) would look like on github?
I still don't have a strong intention to include this since GitHub's Readme API doesn't support it. But since this keeps coming up (#92, #37, #113), and with the newfound focus on the offline renderer (#35), it might be worth taking a serious look.
Keeping this open for discussion and implementation advice.
https://github.com/github/markup is described as "The code we use to render README.your_favorite_markup" so I would guess that the list of supported formats there (which includes .rst) matters more to users of grip than the list of supported formats for the API that grip calls ( https://developer.github.com/v3/markdown/ ). To end users of grip, the calling of that API probably feels like an implementation detail of how grip works internally.
https://github.com/github/markup/blob/master/lib/github/commands/rest2html appears to be the Python script GitHub uses to turn .rst files into HTML. I kind of feel like that whole library could/should be wrapped by grip or something similar. That way you'd get all the formats.
As a workaround you can use readme_renderer which additionally has th eoption to ensure compatibility with PyPI
One work around is to use rst2html.py, optionally with custom css, e.g. https://github.com/matthiaseisen/docutils-css
Also consider restview. https://mg.pov.lt/restview/ No github style, unfortunately.
Perhaps @joeyespo could say: "yes, I would approve of a rst2html pull request", then I'm sure someone will want to pick this up :)?
Also consider restview. https://mg.pov.lt/restview/ No github style, unfortunately.
@reece, while it's hit and miss, I've found the Warehouse/PyPI stylesheets at times produce a closer approximation of the GitHub look than the genuine article. Guessing the selectors are less discriminating. The source is all sass/scss, but the processed goods can be gotten easily enough.
>$ wget -q -nd -e robots=off -p -A "warehouse.*.css" https://pypi.org && mv ware*css warehouse.css
>$ restview --css warehouse.css,restview.css README.rst
Doesn't fix the whole over-sized heading thing, though. Injecting something like this via browser plugin, or whatever, seems to help:
Array.from(document.getElementsByTagName('h1')).forEach(el => el.outerHTML = el.outerHTML.replace(/<([/])?h1/g, "<$1h2"));
Edit: Actually, after glancing at @polyzen's GH source (instead of just rejecting it outright when it didn't work OOTB), it does seem the better choice, given a little finagling:
>$ sed -i "s/\.markdown-body/body/g" github-markdown.css
BTW, it's not worth messing with the .pl-* code-highlighting styles, IMO. For example, GitHub's .pl-k ("k" for keyword, apparently) corresponds to restview's .nb (Pygment's Name.Builtin). But all the Pygments stuff gets in-lined after anything passed as --css <my_styles.css>. Also, sometimes simply leaving out ,restview.css as a fallback yields nicer results.
// demote subheadings
Array.from(document.querySelectorAll("h1,h2,h3")).slice(1)
.forEach(el => el.outerHTML = el.outerHTML
.replace(/(<[/]?h)(\d)/g, (_, m, n) => m + (Number(n) + 1)));
P.S. @joeyespo, sorry for the non-grip chatter; I do use it, and it's amazing. C.C. @mgedmin
Just a thought here. One way to handle this could be to use something like pandoc to convert rst(s) to markdown on the fly, then use the markdown as you normally would.
I ended up here because I tried rendering an org-mode file with grip just to see if it worked (it didn't!)
