rst2a API

Overview

A key goal for rst2a is to lower the barrier of entry for using reStructuredText. rst2a's API provides rendering as a web service. This makes it possible to render reStructuredText documents without having to install a heap of packages locally, or working out how to glue it all together.

rst2a's API is versioned so that updates to the API can be released in a backwards compatible way. The current version of the API is version 1.0.

If you have any issues with the API, you can contact us here.

Rendering Documents

The base rendering URL for the API is: http://api.rst2a.com/1.0/rst2/<format>

There are three ways to convert a reStructuredText document.

The first is to post the contents of the file to be converted to the form variable 'rst' to the above URL for the desired output format.

Alternatively you can pass the location of a reStructuredText document to the variable 'uri'. There is currently a size limit of 250K for remote files rendered via the 'uri' option.

Finally you can pass the 'token' of a file that was previously uploaded with the rst2/token command.

html

http://api.rst2a.com/1.0/rst2/html

Converts a restructured text document to html.

Arguments

required:

  • rst: the text document to be converted to html or
  • uri: location of a document to be converted to html or
  • token: token of a file uploaded with the rst2/token command

optional:

  • style: selects the style to use for the document.

Example usage:

Post a file to the 'rst' variable:

> curl -F "rst=@resume.rst" http://api.rst2a.com/1.0/rst2/html?style=d-scheme > resume.html

Convert a remote resource with 'uri':

http://api.rst2a.com/1.0/rst2/html?uri=http://open.crngames.com/src/inuma/the-red-book.txt&style=d-scheme

http://api.rst2a.com/1.0/rst2/html/styles

Lists the available html styles.

Example response:

<styles>
  <style name="default" />
  <style name="voidspace" />
  <style name="d-scheme" />
</styles>

pdf

http://api.rst2a.com/1.0/rst2/pdf

Converts a restructured text document to pdf.

Arguments

required:

  • rst: the text document to be converted to pdf or
  • uri: location of a document to be converted to pdf or
  • token: token of a file uploaded with the rst2/token command

optional:

  • class: selects the base latex document class to use. defaults to article.
  • style: selects an additional latex style to apply.
  • use-latex-toc: if 'yes', latex will generate the table of contents, otherwise docutils will generate the table of contents. defaults to 'no'.

Example usage:

Post a file to the 'rst' variable:

> curl -F "rst=@resume.rst" http://api.rst2a.com/1.0/rst2/pdf?class=report&style=style2 > resume.pdf

Convert a remote resource with 'uri':

http://api.rst2a.com/1.0/rst2/pdf?uri=http://open.crngames.com/src/inuma/the-red-book.txt&class=scrartcl&style=zope

Have latex generate the table of contents:

http://api.rst2a.com/1.0/rst2/pdf?uri=http://open.crngames.com/src/inuma/the-red-book.txt&class=scrartcl&style=zope&use-latex-toc=yes

http://api.rst2a.com/1.0/rst2/pdf/classes

Lists the available latex document classes.

Example response:

<classes>
  <class name="article" />
  <class name="report" />
  <class name="book" />
</classes>

http://api.rst2a.com/1.0/rst2/pdf/styles

Lists the available latex styles.

Example response:

<styles>
  <style name="default" />
  <style name="style2" />
</styles>

token

http://api.rst2a.com/1.0/rst2/token

Generate a token for a reStructuredText document, which can be used to generate several renderings of a document and to create shareable links.

Arguments

required:

  • rst: the text document to be checked or
  • uri: location of a document to be checked

Example usage:

Convert the introduction to reStructuredText document to a token. An then link to a rendered view:

> TOKEN=$(curl http://api.rst2a.com/1.0/rst2/token?uri=http://docutils.sourceforge.net/docs/ref/rst/introduction.txt)
> curl http://api.rst2a.com/1.0/rst2/html?token=$TOKEN

Example response:

6c15c58148567e8690a8504eb826b8bc

check

http://api.rst2a.com/1.0/rst2/check

Checks the syntax of the supplied reStructuredText document. It returns a JSON list with an item for each error found. If the syntax is correct, an empty list is returned.

Arguments

required:

  • rst: the text document to be checked or
  • uri: location of a document to be checked

Example usage:

Post a file to the 'rst' variable:

> curl -F "rst=@resume.rst" http://api.rst2a.com/1.0/rst2/check

Check a remote resource with 'uri':

http://api.rst2a.com/1.0/rst2/check?uri=http://rst2a.com/static/examples/errors.rst

Example response:

[{
    "message": "Title underline too short.",
    "type": "warning",
    "line": 2,
    "context": "Heading\n===="
}, {
    "message": "Title underline too short.",
    "type": "warning",
    "line": 5,
    "context": "Section 1\n-------"
}]

35 Comments

Subscribe to comments

 #1

dp_wiz - 13th September, 2007 at 12:30 p.m.

Great! How about JSONp services for html?

 #2

Andy Gayton - 13th September, 2007 at 1:27 p.m.

Hey dp_wiz - were hoping to add cross domain JSON support soon.

Thanks for the reminder of Bob's proposal for standardizing cross domain calls.

http://bob.pythonmac.org/archives/200...

Does anyone know of a standard with more traction? Otherwise we will use that.

 #3

Chewie - 16th September, 2007 at 5:24 p.m.

Can't get the curl example to work when the input file (or text) is non-ASCII.

Any clue on that?

 #4

Chewie - 16th September, 2007 at 5:28 p.m.

Forgot to tell: when using the online form, it works like charm. When using curl, it returns nothing.

 #5

Andy Gayton - 16th September, 2007 at 8:41 p.m.

Chewie, could you mail through the file you are working with? I've put the details for the support contact above in the overview section. I'll check out what's going on.

 #6

Garry - 12th December, 2007 at 7:33 p.m.

Hey Andy,

You can totally do preview from vim:

:!curl -F "rst=@%" http://api.rst2a.com/1.0/rst2/html?st... > /tmp/rst2a-preview.html && open /tmp/rst2a-preview.html

Works on Mac OS X. Other OS's just need to change "open" to whatever their launcher is.

This is just a starting point, d-scheme is hardcoded, taken from your example. But I can imagine the possibilities already!

A vim mapping could be made to shorten that up ;)

 #7

the daniel - 12th December, 2007 at 7:34 p.m.

d-scheme is the best one anyway :)

 #8

Andy Gayton - 12th December, 2007 at 8:52 p.m.

@thedaniel: we're about ready for a 0.2 d-scheme? :))

 #9

bartuer - 21st April, 2008 at 6:52 p.m.

crngames stylesheet looks nice!

 #10

era - 27th April, 2008 at 6:19 a.m.

Is PDF generation broken? I just get errors. (Granted, my document might contain syntax errors if your python-docutils is more strict than the copy I have locally. I tried it on another box at one point and it complained.)

 #11

Andy Gayton - 27th April, 2008 at 3:11 p.m.

Heya era,

You can't currently convert documents to PDF which contain images:

http://rst2a.com/about/#c351

Other than that, most documents should convert fine though. Is it possible to send through the document you are trying to convert to here

cheers,

 #12

Björn Lindqvist - 30th June, 2009 at 9:59 a.m.

This is an excellent service! Is it possible to get syntax highlighting to work?

 #15

air max 2010-3-4 - 7th March, 2010 at 8:01 p.m.

Are you prepare a pair of sport shoes this spring,the you can consider of the nike air max,such as air max 90,air max 360,air max 95 and other style shoes.The air max 2009 or air max 2010 are new brand on sale. Special nike air max 90,nike air max 360 and nike air max 95,the three styles of shoes are popular in the world. I suggest you choice the nike air 90 which shoes is hot sale in nike air max 2010,of course you can choice the cheap air max shoes or discount air max shoes.Now the air max shoes sale ,air max 90 sale,air max 360 sale,air max 95 sale are popular by younger,you can let yourself in fashion wear air max shoes .

 #16

Ccboots - 7th March, 2010 at 8:25 p.m.

Paul Smith not only in fashion, but in the wider context of popular culture. This is evident in the overall look of both Paul Smith Shoes, Paul Smith Wallet, Paul Smith Cufflinks and Paul Smith Bags.There are new brand paul smith sale online,such as cheap paul smith shoes ,cheap paul smith bags,cheap paul smith wallets,cheap pual smith cufflinks,Paul Smith is an English fashion designer, whose business and reputation is founded upon his menswear.So you should take a look of the paul smith shoes sale, paul smith bags sale,paul smith wallets sale,pual smith cufflinks sale, etc.You must be love these paul smith on sale.

 #17

glasses - 7th March, 2010 at 8:49 p.m.

It has been long before I can find some useful articles about Nintendo DS Lite. Your views truly open my mind.
Thank you so much for sharing some great ideas of Nintendo DS with us, they are helpful.
I love this DS Lite article since it is one of those which truly convey useful ideas.
I appreciate your bright ideas in this DS Lite Console article. Great work!
We share the opinion on Nintendo DS Lite Console and I really enjoy reading your article.
What an inspiring article you wrote! I totally like the useful NDS info shared in the article.
I am glad to read some fantastic nintendo ds card article like this.
Great resources of ds card! Thank you for sharing this with us.

 #18

glasses - 7th March, 2010 at 8:49 p.m.

when washing eyeglasses under running water
people may ask whether prescription sunglasses cleaners
glasses need bath and cleaning to keep a good
Thanks for the glasses online info, it helps a lot.
I totally like the useful eyeglasses online info shared in the article.
your glasses need bath and cleaning to keep a good
Some people may ask whether eyewear cleaners
Since glasses are sort of delicate
when washing eyeglasses under running water
give your cheap glasses a nice bath
when washing eyeglasses under running water

 #19

ghd iv styler - 7th March, 2010 at 9:03 p.m.

ghd iv styler
ghd hair Straighteners
ghd mk4

 #20

nike shox - 7th March, 2010 at 10:23 p.m.

as we konw,nike is a famous brand both in domestic and international markets, such as nike dunks,nike shox,nike air max,air force 1,nike dunk SB,etc.it is of high prestige for the young attached to having a pair of nike shoes,cuz it is of best quality super functionality and lastest design.would you like to be a current man?my-shoes-shop is at your service.i have the impression that you will indulge yourself in the nike shoes at the very sight you see that classics in our shop. we are looking forward to your coming.

 #21

nike shox shop - 7th March, 2010 at 10:34 p.m.

Nike shop http://www.nike-shox-shop.com/ bringing a new classic shoes!Welcome to purchase on selection.

 #24

wangxiaowen - 8th March, 2010 at 1:26 a.m.

=======================================================================
http://www.handbags-shop.com

handbags purses
bags cheap Handbags
designer Handbags designer purses

buy handbags buy purses
fake purses fake bag
fake handbags discount bags

=======================================================================
http://www.sellcheaphandbags.com

cheap handbag cheap purses
designer purses designer bags
designer handbags authentic handbags

replica handbags replica bags
replica purses cheap bags
================================

 #25

wds - 8th March, 2010 at 2:04 a.m.

Can you find the replica handbags wholesale?
How to Find designer handbags on sale?
Bottega Veneta Handbags High End Designer Goods.
Why Burberry Handbags Are So Hot?
Why Cartier Handbags Are So Hot?
Why Celine Handbags Are So Hot?
Why Chanel Handbags Are So Hot?
Give My Love to Christian louboutin sale.
Why Do replica Christian Louboutin Get Termed As True Blue Blood?
Great cheap designer shoes!

 #29

replicas bags - 8th March, 2010 at 7:58 p.m.

Just continue writing thisreplicas bags kind of post. I will be your loyal reader. Thanks again.

 #30

fdgdf g - 9th March, 2010 at 4 a.m.

hat a great post! Now let me tell you more information about http://www.famousbrandbag.com/Givench... Handbags. It is made from the best material as well as http://uggboots-euro.com/UGG-Women... Women's Handbags. The designer made a great decision to add http://www.famousbrandbag.com/Tiffany... Money Clips in its zipper chain. It will look great with all outfits.Both http://sell-ugg.com/UGG-Sundance-Limi... Sundance Limited Edition and http://uggboots-euro.com/UGG-Classic-... UGG Classic Tall Patent Paisley boots can add its chic design.

 #31

chanel handbags - 9th March, 2010 at 7:11 a.m.

balenciaga handbags
http://www.olugg.com/specials.html
ugg classic tall
[url=http://www.olugg.com/handbags-mulberry-handbags-c-490_510.html]mulberry handbags[/url]
[hermes handbags->http://www.olugg.com/handbags-hermes-handbags-c-490_502.html]
[link= http://www.olugg.com/ghd-hair-straigh... ghd hair straightener [/link]

 #32

handbags balenciaga sale - 9th March, 2010 at 7:13 a.m.

Regardless of the trend of the times and social fashion balenciaga handbags, people always can with noble quality, beyond time and society, walk oneself the ugg classic tall bootscorrect road. now, everybody to refrigerators, automobiles and houses and rush, chase, competition. this mulberry handbags is the characteristic of our age. but also have many people, they ghd hair straightener don't pursue these material things, they pursue and truth, the hermes handbags inner freedom and peace.

 #33

jordan shoes - 10th March, 2010 at 1:59 a.m.

Petition is pretty straight forward and is NOT intended to serve as a vehicle to extol the merits of Nike Dunks Low communications. (There is time enough to sing the praises of air jordan Internet Air Jordan Shoes Nike Jordan Shoes Jordan Retro Shoes Wholesale Jordan Shoescommunications, but we Air Jordans Shoes and Nike Kicks and wholesale nike shoes did not want this issue to be held back over a battle over preferred technologies.So I introduce to you the shoes are .Thank you for your attention.

 #35

groupshoes - 10th March, 2010 at 8:06 a.m.

I'm a little late finding this article, but I loved it.

Do you love sports, do you feel like to look cool, i got a very awesome website here introduced by one of my friends. Very good website where you can find the Authentic nike shoes with latest and huge style of nike air max shoes and dunk sb shoes. I have bought from them for so many times, and very satisfied with the their goods and service.Such as Air max 1, air max 2, air max 90, nike air max 2009+, air max 2010 new, nike air max TN, nike air ltd trainers, air max 95.Air max 360 running shoes, nike shox shoes. Though their price are low, don't worry about it's quality.


Christmas is coming, go there to find presents for your friends or family. They are on sale, limited time!

Post a comment