rst2a was conceived by Andy Gayton, David Stokes, and Asi Behar as a solution to a persistent problem that plagued the team during their day jobs at Revver.
Every time a spec was needed, invariably, a debate over the format of the spec would arise - with developers preferring a plain text document on a wiki, and business people preferring traditional tools such as Microsoft Word based on a set template.
Cue reStructuredText - an easy-to-read, plain text document format designed to keep content and the style/formatting of content separate. Author the content once, then present it in a variety of formats - like html and pdf - with infinite possibilities for styles and templates.
After numerous proprietary-format-written specs that he couldn't open, Andy decided to build rst2a as an advocacy site to accomplish a few goals:
- Encourage the creation of additional rst styles.
- Present these styles in a digestable way, for people to download and use.
- Make it easy to convert rst documents to multiple formats, without having to install a heap of software locally.
- Help establish rst as a viable format for non-technical users.
Check out some examples of what it can do today, or give it a try right now!
Despite being awesome, there aren't a lot of styles for reStructuredText ... yet. We really need your help. Do you have any styles lying about on your hard disk?
If so, please send them through! Or try your hand at creating a style!
To send through a style, email the .css, or .tex file to: igotstyle@rst2a.com. Please include the following details:
- A short name for the style. e.g. revver-dev, lsr.
- The style's author.
- A short description of the style. This can describe the styles origin, or a particular use the style is good for.
You can contact us here.
rst2a was developed by:
| Andy Gayton: | Wordless Code Monkey |
|---|---|
| David Stokes: | Design / Workflow |
| Asi Behar: | Styling / Markup |
and made possible by a myriad of open source projects, including Docutils (of course :)), Python, Django, MochiKit, LaTeX, ImageMagick (everything looks better with a drop shadow ;)), MySQL, Ubuntu
Garry - 9th September, 2007 at 3 a.m.
Congratulations on the launch!
Isaac Behar - 9th September, 2007 at 10:06 p.m.
To the team:
Congratulations on the launch!
Keep up the good work!
Jackson Gates - 9th September, 2007 at 10:28 p.m.
Well done guys. Good luck and let me know how I can help.
Shpongle Spawn - 9th September, 2007 at 10:37 p.m.
Lookin' good. No idea what the hell it is ... but lookin' gooood!
the daniel - 10th September, 2007 at 2:51 p.m.
brilliant! now that we have rst2a, world peace is just around the corner!
Andy - 11th September, 2007 at 2:04 a.m.
Looks good.
Is making this a distributable open source app on the roadmap? It might be nice not have to rely on an online service.
Christian - 11th September, 2007 at 2:39 a.m.
Hi,
so whats the point? is it just markdown + some web interface to generate different styles of pdf/html?
why did you invent a new style-language? there are a lot all ready for all the wiki and blog engines.
markdown, textile, wordpress, bbcode. Do we really need another one?
i think this site is great, it is definitely one of the easiest to use pages, nu fluff, just stuff to do things. That is the bonus, the really nice interface to a lot of shell scripts.
ciao
Christian
Roberto - 11th September, 2007 at 7:57 a.m.
Andy: go to docutils.sf.net
Christian: go to docutils.sf.net and then figure out rst has been around for at least 5 years.
Andy Gayton - 11th September, 2007 at 10:12 a.m.
This came up over here as well: http://programming.reddit.com/info/2n...
All of the rendering tools used at rst2a are freely available for you to use locally.
Jim - 11th September, 2007 at 10:29 p.m.
http://pygments.org/docs/rstdirective/
Pretty useful example using pygments python lib for source-code highlighting within rst docs.
David Goodger - 13th September, 2007 at 10:16 a.m.
Very cool!
One issue: the HTML title on the home page says "Restructured Text" (2 words). It should be "reStructuredText" (one word, embedded capitalization).
Sérgio - 13th September, 2007 at 10:59 a.m.
Great tool! Are you considering supporting Wiki Creole?
Shawn Wheatley - 13th September, 2007 at 12:59 p.m.
Fantastic work guys! I've been looking into a Django-powered ReST engine for my blog. Do you think you could post a little more about the design of the app?
Alexander Solovyov - 13th September, 2007 at 1:31 p.m.
Great service. Thanks for it!
Andy Gayton - 13th September, 2007 at 1:42 p.m.
David: Thank you for docutils! :), That's fixed.
Sérgio: I don't think its likely in the near future. We are thinking of supporting markdown -> reStructuredText -> a (hoping to expand on a soon).
Shawn: It's really pretty basic at the moment. The site is currently just wrappers for rst2html and rst2latex/pdflatex. We're hoping to flesh out the site with additional features, overtime - a write up might be more interesting then.
Asi Behar - 13th September, 2007 at 3:09 p.m.
@David Goodger
Yeah, that would have been my fault. Sorry about that. Full disclaimer: I am a rst n00b (Andy started building this to trump my pretty MS Word-based specs :).
Chas - 14th September, 2007 at 5:32 a.m.
Thanks for your initiative. I love rst more than ever thanks to You.
Aibek - 14th September, 2007 at 11:49 a.m.
Thanks Guyz, excellent application. I will recommend it to my readers (MakeUseOf.com)
Baiju M - 17th September, 2007 at 1:31 a.m.
There is HTML style here: http://svn.zope.org/Zope3/trunk/doc/s...
Please include it.
Andy Gayton - 17th September, 2007 at 3:22 a.m.
Thanks for the pointer Baiju.
That's up: http://rst2a.com/news/4/
Baiju M - 19th September, 2007 at 2:05 a.m.
Hi Andy,
Thanks for adding that HTML style. I have one more request. I prefer to use "--use-latex-toc" option of rst2latex.py , and in the document I will use ".. contents::" directive *without* ".. sectnum::" directive. Now if I run paflatex *two* times, I will get a nice table of contents. Can you incorporate this feature in the next API update.
Andy Gayton - 19th September, 2007 at 1:32 p.m.
Baiju, good tip - we'll try to add that soon.
Scott R - 20th September, 2007 at 9:52 a.m.
I use Textile (within Backpack) frequently for creating documents. Textile has elements for creating and formatting tables. Is this available in rst2a? Is there a more comprehensive syntax guide available?
Andy Gayton - 20th September, 2007 at 12:18 p.m.
Hey Scott, yeah, the current legend panel is pretty wimpy. more comprehensive documentation is available here: http://docutils.sourceforge.net/docs/...
Scott R - 28th September, 2007 at 10:25 a.m.
Any plans for secure generation of documents via HTTPS? What happens to the text files that are uploaded to your site or processed via the API?
Andy Gayton - 30th September, 2007 at 3:38 a.m.
Scott, we're looking to get a privacy policy in place.
We are thinking something along these lines:
To support rendering large files multiple times, we're adding a rst2/token call to the API. This will keep a file on the server, which can be referenced via the token. Files with tokens will be removed after 24 hours.
All other API uses will remove the file immediately.
This should be in place in the next couple of weeks. I'll try and add https support at the same time.
Down the track we think it'll be cool to support registered users who can upload files, and have the option of making rendered views of these files available for others.
Andy Gayton - 30th September, 2007 at 4:11 a.m.
Baiju, the API now supports the --use-latex-toc option for PDF generation:
- http://api.rst2a.com/1.0/rst2/pdf?uri...
Scott Paley - 5th October, 2007 at 1:51 p.m.
This was working fantastically well for me - thank you very much for doing this!
I've been trying to use it all afternoon and keep getting an error message. I presume you know about it, but wanted to make sure.
Andy Gayton - 5th October, 2007 at 3:07 p.m.
Hey Scott, yep, getting an exception from latex coming through:
Package typearea Warning: Bad DIV-value!
(typearea) You should decrease DIV, increase fontsize or
(typearea) change papersize.
I'll try and take a look at what's up this weekend.
Andy Gayton - 8th October, 2007 at 7:33 a.m.
@Scott Paley,
Ah, I read the exception mail too quickly. The above message was just a warning. The real issue is:
! LaTeX Error: Too deeply nested.
LaTeX limits how deeply you can nest bullet items. I've added an error message so you can see when the limit is being hit:
http://api.rst2a.com/1.0/rst2/pdf?uri...
This is only a limitation for PDF rendering. HTML documents work fine:
http://api.rst2a.com/1.0/rst2/html?ur...
If anyone knows of a way to work around this - please let us know!
Santosh Patnaik - 8th November, 2007 at 2:05 p.m.
Might be relevant: rTxt2htm, a PHP script that generates HTML versions of plain-text readme files written using a simple and unobtrusive syntax.
Zajcev Evgeny - 6th December, 2007 at 12:44 p.m.
Thank you for resource! ReST is just great
What about adding "External URL" source besides "Upload file" and "Type a Document", so people could process ReST files already placed in the internet...
Andy Gayton - 6th December, 2007 at 6:18 p.m.
Hey Zajcev, thanks for the feedback, hopefully this will be a useful tool for you.
Rendering external URLs is supported!
Check out:
http://rst2a.com/news/3/convert-remot...
Andrew - 11th December, 2007 at 4:41 p.m.
Your site finally convinced me to adopt restructuredtext! Very nice work, it is a pleasure to use a tool with this kind of support behind it. Good luck!
Clint Laskowski - 19th December, 2007 at 10:50 p.m.
Check out InType a Windows text editor with a cool feature for creating RST documents. Could this functionality be built in to RST2A?
-- Clint (clint at bluehatsecurity (.) com)
Max Battcher - 31st January, 2008 at 3:13 p.m.
Any thoughts on Wikir_? It's a project to allow reformatting reST into Wiki syntax, focusing on Google Code Wiki syntax, but seems to be hoping for compatibility with Moin Moin and Trac as well. I'm not sure if its necessary or useful for RST2A to support it, but it certainly adds more to the "anywhere".
.. _Wikir: http://code.google.com/p/wikir/
Ralph Green - 8th April, 2008 at 12:18 a.m.
Howdy,
It is an interesting idea. I suspect I would be more interested in recipes on how to do this on my own machine. I would give your system a try, but the web site does not work for me. All I see is a bunch of empty boxes and descriptions beside them about what presumably would be in those boxes.
Good luck
Andy Gayton - 8th April, 2008 at 1:17 p.m.
Hey Ralph,
You can download the various style sheets for use on your own machine. rst2a is just a place to submit and find available styles - although if you don't want to install everything locally you can use us for conversion too.
Which browser are you using? We've tested the site in IE>6, Firefox and Safari - if you are seeing empty boxes though it sounds like something is awry.
Ralph Green - 8th April, 2008 at 5:48 p.m.
Howdy,
I am running Firefox 2.0.0.13 on Ubuntu Gutsy Gibbon. All updates have been applied. I have the following addons installed in Firefox. 1. Adblock, 2. Bookmard Sync and Sort
3. FasterFox, 4. GoogCal 5. Greasemonkey, 6. NoScript, 7. Server Spy 8. Ubuntu Firefox Extension 9. Web Developer.
How do you download a style and use it locally. One member of our company wants to convert all our documentation to use your system. I don't mind, if we have a backup way of generating documents like pdf files from our restructuredText.
Andy Gayton - 9th April, 2008 at 2:34 a.m.
@Ralph: I just gave it a quick test with Firefox 2.0.0.13 on os x and Firefox 2.0.0.11 on Gutsy, and everything works ok for me. Out of your plugins, NoScript looks the most suspect. Could you just check that NoScript isn't blocking javascript for rst2a?
Any time you preview a style on the site, there's an underlined down arrow that you can click to download the style.
Here's a quick screen shot to show where:
* http://rst2a.com/static/examples/rst2...
These download links are available from the style gallery as well:
* http://rst2a.com/gallery/html/
Ralph Green - 9th April, 2008 at 4 p.m.
Andy,
NoScript is definitely blocking Javascript. Browsing with javascript is dangerous and I did not see any hint it was needed. I'll have to setup a test machine somewhere if javascript is needed. It would be irresponsible to use javascript on my main work machine. Thank you for the feedback.
Ply - 25th April, 2008 at 11:12 p.m.
Hello,
My text file includes a call to an external image using the directive ".. image:: http://www.mysitehere.com/images/myim.... It works while generating a html page but not with a pdf.
Should I be calling it differently or are images not supported in pdf creation?
Thanks
Andy Gayton - 27th April, 2008 at 2:58 p.m.
Hey Ply,
Yeah, this is a known issue. pdflatex, which is used to convert ReST to PDFs requires images to be local. One of our users, Zack Voase has sent us some code which downloads remote images to be used local for the ReST to PDF conversion:
http://github.com/cablehead/rst2a/tre...
I just need some spare time to be able to integrate Zack's work with rst2a.
Ply - 28th April, 2008 at 12:07 p.m.
Thanks, Andy. Looking forward to it. Great website.
h4xp3t - 4th May, 2008 at 3:42 a.m.
I second Ralph's comment -- if your site requires JavaScript (as I'm sure it does, what with all the AJAXy round corners :-) -- then for the love of ${dmr}, make it fail gracefully for those of us who cannot or don't want to surf with JavaScript on by default. People are scared of error messages but stuff which Plan Old Just Doesn't Work with no indication what's wrong is even worse.
Glafkos - 4th June, 2008 at 9:02 p.m.
What a great site!Thank you,
Mark - 10th July, 2008 at 1:59 p.m.
Cool, thanks.