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 (all five of docutils' own sequences — arabic, loweralpha/upperalpha, lowerroman/upperroman — in all three formats, see enum.go), 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", "table", "list-table" (see Options and tabledirective.go), and the nine generic admonitions plus "admonition" itself (see admonitions.go) — there is still no general per-directive registry beyond those), 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. Section titles (both overlined and underline-only), their consistency-tracking (title_styles, real docutils' check_subsection — a title style's LEVEL is fixed by the order it's first seen in the whole document, and skipping more than one level deeper than the current nesting is an error), and their various diagnostics (too-short overline/underline, missing/mismatched underline, incomplete title, invalid title-or-transition) are ported — see matchTitle/titleDiagnostic/checkSubsectionLevel in parser.go. Not yet ported: the match_titles=false diagnostics for a title-looking construct found somewhere titles aren't allowed (inside a block quote or list item — real docutils still errors there, "Unexpected section title[. / or transition.]"; this parser currently treats it as plain text silently), and enumerator-sequence validation (docutils errors on a non-consecutive ordinal; this parser doesn't check).

Index

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

Functions

func MakeID

func MakeID(s string) string

MakeID returns the identifier reStructuredText derives from a name — docutils' own nodes.make_id, and the exact rule this package uses for a section's implicit target, a hyperlink target's anchor and every other generated id.

It is exported for consumers that need to ask "would this id be produced anyway?" — go-richdoc/rst's writer, for one, emits an explicit ".. _id:" target before a heading only when the heading's own title would NOT already slug to that id, since emitting it regardless produces a genuine duplicate-name diagnostic on reparse (see dupnames.go). Reimplementing the rule downstream would duplicate this package's asciiFold table and drift from it.

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

	// ReportDanglingReferences rewrites a reference with no matching
	// target into a <problematic>, and appends one trailing
	// "Docutils System Messages" section collecting every such
	// diagnostic.
	//
	// It defaults to FALSE, because that rewriting is not parsing: real
	// docutils does it in the DanglingReferences and Messages TRANSFORMS,
	// which run after the parser and which a caller may never run at all.
	// A bare Parse therefore leaves an unresolved reference exactly as
	// docutils' own bare parse does — a <reference> carrying its refname
	// and no refuri — and a consumer that wants the diagnostics opts in.
	//
	// References that DO resolve are unaffected either way: their refuri
	// is filled in during parsing regardless, which is what makes this
	// package usable without a transform pipeline.
	ReportDanglingReferences 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.