rst

An agent works with this tool through a standard file-based editing and compilation pipeline. It drafts source text files with .rst extensions and then triggers shell commands like rst2html.py or pandoc to render them. When the compiler encounters formatting problems, it outputs explicit syntactic error messages containing specific line numbers, allowing the agent to systematically locate and correct errors in a closed loop.

The markup syntax supports robust automated editing because rules on directives, table layouts, and section headers are concrete. For example, directives like .. list-table:: rely on consistent indentation and explicit options like :header-rows: 1. Underline headers must span at least the length of the title text. These strict, checkable constraints allow the agent to verify its formatting deterministically and ensure that complex elements like code blocks, hyperlinked text, and images render correctly in the final HTML.

The state of the document is entirely preserved within the plaintext .rst file, which benefits multi-turn workflows and agent handoffs. If a new agent session resumes from existing files, it can build upon or modify the source without breaking prior formatting or introducing compounding syntax errors. This flat-file structure prevents state corruption and simplifies agent memory constraints.

However, the toolchain behaves unreliably across repeated executions. Even when the source code remains identical and correct, repeated compilation runs frequently fail due to environment or utility instability. This unpredictable execution profile disrupts automated feedback loops, forcing the agent to handle tool failures that do not stem from its own syntax mistakes.

This tool is a good fit for agents tasked with generating deeply structured documents containing nested sections, tables, and nested code blocks. Its explicit syntax rules and informative compiler warnings allow the agent to systematically author and repair complex technical documents. It is also well-suited for asynchronous workflows where progress must be safely handed off to subsequent agent sessions using simple, plaintext source files.

It is a poor fit for workflows that require highly stable and repeatable execution pipelines. The run-to-run instability of the compiler utilities makes it unsuitable for pipelines where intermittent CLI crashes or infrastructure rendering failures cannot be tolerated. Agents in these environments will waste processing steps attempting to resolve environment errors rather than document content issues.

An agent utilizes an edit-compile-execute loop to author reStructuredText documents, compile them, and resolve syntax errors reported by the parser.