Documentation

There are two ways to use the API - the first is to post a restructured text document to the api and it will be converted into html for you. The output HTML is available as plaintext or as JSON or even rendered direct to the browser - this is probably only useful for demo purposes though.

The alternative approach is to use the GET api to provide a url of a rst resource which will be fetched and parsed for you.

Required API Parameters

URL:

http://restructuredtext.appspot.com/api/v1/rst2html/

Valid for both POST and GET

rst (POST only):

text marked up as reStructuredText

(Note: only valid for <strong>POST</strong> requests)

rst_url (GET only):

Specify the url to an rst file to be processed

e.g: "http://example.com/amazing.rst" (Note: only valid for GET requests)

Optional API Parameters

output_type:

The output format. Choose from html, html_plain, json. - "html": Returns HTML as text/html - "html_plain": Returns HTML as text/plain</li> - "json": Returns JSON as text/plain</li>

e.g: "html_plain". (Note: The default is "html")

document_output:

What part of the document to return - choose from "full" or "body". If not set the default is "body".

A full document is the entire html document including the doctype.

initial_header_level:

Sets the heading level that is used beyond the title. If a title is present this will be an H1 so the default is set to 2 as only one h1 should exist on a page.

e.g: 3.

highlight_style:

Choose a stylesheet for code syntax highlighting. If not set you can still provide your own styles via the css_url parameter.

e.g: {{pygment_styles}}

css_url:

Specify the url to a CSS file to be included in the source to provide styling. For more than one css file comma separate the stylesheets.

e.g: "http://example.com/rst.css"

callback:

Allows a callback value to be specified for script inclusions to work.

e.g: "foo" (Note: only valid when "output" is "json")

Errors

All errors are returned in JSON format. Should you hit an error it's likely to look something like this:

{
    "error": true,
    "message": "Invalid remote resource - please check the rst_url parameter"
}

SourceCode Highlighting

The sourcecode hightlighting is possible with rst directives. All of the following directives are equivalent:

.. sourcecode:: python

    import os

.. code:: python

    import os

.. code-block:: python

    import os

Resulting in the following:

import os