Novus Convert
Convert files
Document format

RST converter

An .rst file is a reStructuredText document: plain-text markup where headings are made by underlining a line with punctuation, and where an extensible directive syntax lets a document embed anything the processor knows how to render. It is the native language of Python's documentation.

Private for supported formats — processed in your browser

Convert supported files

Runs on your device

Drop RST files here

Batch files can each use a different output. Nothing uploads for local conversions.

Working inputs include camera RAW, browser-local audio/video, PDF, CBZ/CBR comics, office documents, ebooks, markup, 3D models, structured text, images, and archives.

Where RST comes from

David Goodger designed reStructuredText in 2002 as part of the Docutils project, aiming for markup readable enough that a plain-text file was already a decent document. Sphinx, released in 2008 to document Python itself, built cross-referencing, indexing and multi-format output on top of it, and in doing so made reST the standard for Python library documentation and for Read the Docs.

How RST works

  • Headings are formed by underlining text with a punctuation character; the character does not matter, but the order in which characters first appear defines the level hierarchy for the whole document.
  • The underline must be at least as long as the title, which is the single most common source of parser warnings.
  • Directives use the .. name:: form and are the extension mechanism — Sphinx adds dozens, so a file may be unreadable without knowing which processor it targets.
  • Indentation is significant and defines block structure, so a stray space changes meaning.
  • Roles like :ref: and :class: provide inline semantics that Markdown has no equivalent for.

When to use RST

  • Python package documentation, especially anything built with Sphinx
  • Read the Docs projects and their cross-referenced API documentation
  • Converting legacy Python documentation to Markdown for a new platform
  • Extracting prose from a documentation tree for review or translation

Strengths and limitations

Strengths

  • Extensible through directives without inventing new syntax
  • Strong semantic cross-referencing, which plain Markdown cannot express
  • A single reference implementation, so behaviour is predictable

Limitations

  • Underline-based headings are fiddly and easy to get subtly wrong
  • Significant indentation makes editing error-prone
  • Files that rely on Sphinx directives are not really portable reST

Compatibility

Docutils, Sphinx, GitHub, GitLab, PyPI and Read the Docs all render reStructuredText. Novus Convert reads it locally without raw directives or file includes — both of which would otherwise let a document pull in arbitrary content — and converts to HTML, Markdown and plain text.

Docinfo fields are read as document metadata; the targets have no structured field to carry them into.

Convert RST to another format