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-------"
}]

11 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,

Post a comment