rst

Documentation

Overview

Package rst is a reStructuredText parser producing a doctree.Element document tree, modeled on docutils.parsers.rst.states.

SCOPE (v1 — see [[go-docutils-org]] for the plan): sections (over/under lined titles), paragraphs, transitions, bullet lists, enumerated lists (arabic + '.' suffix only), field lists, definition lists, line blocks (nested by relative indentation, see lineblock.go), doctest blocks, block quotes, literal blocks, comments, directives (captured structurally only, except "raw", see Options — there is still no per-directive registry beyond that one case), hyperlink targets with reference resolution (named, indirect, and anonymous — see explicit.go), footnotes, citations, substitution definitions, docinfo promotion, simple tables and GRID tables (see table.go and gridtable.go), and the inline markup in inline.go. Title-style consistency and enumerator-sequence validation are not enforced (docutils errors on inconsistent styles or skipped levels; this parser silently assigns a level instead).

Index

• func Parse(source string) *doctree.Element
• func ParseWithOptions(source string, opts Options) *doctree.Element
• type Options
  • func DefaultOptions() Options

Functions

func Parse

func Parse(source string) *doctree.Element

Parse parses reStructuredText source into a document tree, using DefaultOptions.

func ParseWithOptions

func ParseWithOptions(source string, opts Options) *doctree.Element

ParseWithOptions is Parse with explicit control over the behaviors Options exposes.

Types

type Options

type Options struct {
	// RawEnabled allows the "raw" directive (`.. raw:: FORMAT`) to pass
	// its content through completely unprocessed, tagged with the target
	// format it's meant for — real docutils' own real security surface
	// for untrusted input, since the content is never parsed as reST at
	// all. Real docutils defaults this true (its own --no-raw flag's
	// help text: "Enable the raw directive. (default)"), matched here;
	// disabled, the directive falls back to this project's existing
	// structural capture, the same as any other unimplemented directive.
	RawEnabled bool
}

Options configures Parse's behavior. The zero value is NOT what Parse itself uses — see DefaultOptions — so a caller building one by hand should start from DefaultOptions and override specific fields, not construct Options{} directly (its RawEnabled would silently come out false, the opposite of what Parse/DefaultOptions actually do).

func DefaultOptions

func DefaultOptions() Options

DefaultOptions returns the Options Parse itself uses, matching real docutils' own defaults.