rdoc

package module
v0.0.0-...-1c2a041 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 17, 2026 License: BSD-3-Clause Imports: 2 Imported by: 0

README

go-ruby-rdoc/rdoc

rdoc — go-ruby-rdoc

Docs License Go Coverage

A pure-Go (no cgo) reimplementation of the core of Ruby's RDoc documentation tool — the markup parser, the inline attribute manager, the document model and the HTML formatter, plus a focused reader of Ruby source comments into the RDoc code-object model. It turns RDoc markup text into the exact HTML the rdoc gem emits, and reads class/module/method/constant/attribute declarations together with their attached documentation comments — without any Ruby runtime.

It is a sibling of go-ruby-regexp (the Onigmo engine), go-ruby-erb (the ERB compiler) and go-ruby-yaml (the Psych emitter), and is intended as the documentation backend for go-embedded-ruby.

What it is — and isn't. Parsing RDoc markup into the document model and rendering it to HTML/Markdown/RDoc is fully deterministic and needs no interpreter, so it lives here as pure Go with byte-for-byte parity against the gem. Two things are host seams: (1) verbatim Ruby syntax highlighting, because the gem's parseable? check evaluates the block with the real Ruby parser — a built-in HighlightRuby covers the common token classes, gated behind an HTMLOptions.Parseable callback; and (2) the on-disk darkfish HTML-site/template generation (file-walking, asset copying), which is a thin output-writing layer left to the caller.

What works

  • RDoc::Markup::Parser — a faithful recursive-descent port producing the document model: paragraphs, headings (= H1 … ====== H6), bullet / numbered / lower-alpha / upper-alpha / label ([x]) / note (x::) lists (nested), indented verbatim/code blocks, rules (---), block quotes (>>>) and blank lines.
  • RDoc::Markup::AttributeManager — the inline markup engine: *bold*, _emphasis_, +code+, the <b>/<i>/<em>/<tt>/<code> HTML tags, backslash escaping, __word__ protection, hyperlinks ({text}[url], word[url], bare URLs, link:/mailto:/ftp:/www.), rdoc-ref:/rdoc-label:/rdoc-image: links and cross-references.
  • RDoc::Markup::ToHtml — renders the model to the gem's exact HTML, including heading anchors (id="label-…" via ToLabel), the smart-quote/dash/ellipsis/ ©/® entity pass (RDoc::Text#to_html), pipe mode, and cross-reference linking (ToHtmlCrossref).
  • RDoc::Markup::ToMarkdown / ToRdoc — the Markdown and RDoc-markup formatters for the common block constructs.
  • Code-object extraction — reads Ruby source into TopLevel / ClassModule / AnyMethod / Constant / Attr / Alias with attached comments, visibility (public/private/protected), method parameters, call-seq:, namespace expansion (class A::B → module A + class B) and =begin/=end block comments.

Usage

import "github.com/go-ruby-rdoc/rdoc"

html := rdoc.ToHTML("= Title\n\nA *bold* word and a {link}[https://example.com].\n")
// "\n<h1 id=\"label-Title\">…</h1>\n\n<p>A <strong>bold</strong> word …</p>\n"

doc := rdoc.Parse(markup)          // the document model
md  := rdoc.ToMarkdownString(markup)
rd  := rdoc.ToRdocString(markup)

top := rdoc.Extract("foo.rb", source) // the code-object model
for _, cm := range top.ClassesAndModule {
    // cm.Name, cm.Comment, cm.Methods, cm.Constants, cm.Attrs, …
}
Ruby highlighting

Verbatim blocks are emitted as a plain <pre> by default (the deterministic, Ruby-free path). To reproduce the gem's syntax-highlighted <pre class="ruby">, plug in the built-in highlighter and a Parseable oracle:

opts := &rdoc.HTMLOptions{
    OutputDecoration: true,
    Highlighter:      rdoc.HighlightRuby,        // built-in token highlighter
    Parseable:        myRubyParseableCheck,      // host seam: is this valid Ruby?
}
f := rdoc.NewToHtml(opts)
doc.Accept(f)
out := f.EndAccepting() // not exported — use rdoc helpers; see godoc

Faithfulness

Parity is enforced by a differential oracle: golden HTML / labels / Markdown / RDoc / highlighter / extraction expectations captured from the real rdoc gem (RDoc 7.x) live in testdata/ and are checked on every run. The deterministic, Ruby-free tests alone hold 100% coverage, so CI passes without a Ruby toolchain; the lanes that have Ruby additionally re-derive and re-check the same shapes.

Tests & coverage

GOWORK=off go test -cover ./...

100% statement coverage is enforced in CI across three OSes (Linux/macOS/Windows) and the six supported 64-bit architectures (amd64, arm64, riscv64, loong64, ppc64le, s390x).

License

BSD-3-Clause. Copyright the go-ruby-rdoc/rdoc authors.

WebAssembly

Being pure Go (CGO=0), this library also compiles to WebAssembly — both GOOS=js GOARCH=wasm (browser / Node.js) and GOOS=wasip1 GOARCH=wasm (WASI). CI builds both targets on every push, alongside the six 64-bit native/qemu arches.

GOOS=js     GOARCH=wasm go build ./...   # browser / Node
GOOS=wasip1 GOARCH=wasm go build ./...   # WASI (wasmtime, wasmer, wasmedge, …)

Documentation

Overview

Package rdoc is a pure-Go (CGO=0), MRI-faithful port of the core of Ruby's RDoc documentation tool (the "rdoc" gem): the markup parser, the inline attribute manager, the document model and the HTML formatter, plus a focused reader of Ruby source comments into the RDoc code-object model.

The implementation mirrors RDoc::Markup::Parser, RDoc::Markup::AttributeManager, RDoc::Markup::Document and RDoc::Markup::ToHtml from rdoc 7.x. The goal is byte-for-byte parity with the gem on the markup -> HTML path for the markup constructs the gem supports.

The file-system walking and on-disk "darkfish" HTML-site template generation of the real gem are deliberately out of scope: they are a thin host seam. Everything here is pure, deterministic, in-memory computation.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func HighlightRuby 

func HighlightRuby(code string) (string, bool)

HighlightRuby highlights Ruby source the way RDoc does, returning the HTML and true on success. For constructs this focused highlighter does not model faithfully it returns ("", false) so the caller falls back to a plain block.

func ToHTML 

func ToHTML(markup string) string

ToHTML is a convenience: parse markup text and render to HTML with default options, equivalent to the gem's markup -> ToHtml round trip.

func ToMarkdownString 

func ToMarkdownString(markup string) string

ToMarkdownString converts markup text directly to Markdown.

func ToRdocString 

func ToRdocString(markup string) string

ToRdocString converts markup text through the model and back to RDoc markup (a normalisation round-trip).

Types

type Alias 

type Alias struct {
	NewName string
	OldName string
	Comment string
}

Alias is an alias_method / alias declaration. Mirrors RDoc::Alias.

type AnyMethod 

type AnyMethod struct {
	Name       string
	Params     string // parameter list including parentheses, e.g. "(a, b)"
	Singleton  bool   // true for "def self.x" / "def Klass.x"
	Visibility Visibility
	Comment    string
	// CallSeq is the contents of a "call-seq:" directive in the comment, if any.
	CallSeq string
}

AnyMethod is a method declaration. Mirrors RDoc::AnyMethod.

type Attr 

type Attr struct {
	Name       string
	RW         string // "R", "W" or "RW"
	Visibility Visibility
	Comment    string
}

Attr is an attr_reader/writer/accessor declaration. Mirrors RDoc::Attr.

type BlankLine 

type BlankLine struct{}

BlankLine marks a blank line between blocks. Mirrors RDoc::Markup::BlankLine.

type BlockQuote 

type BlockQuote struct {
	Parts []Element
}

BlockQuote groups indented quoted blocks. Mirrors RDoc::Markup::BlockQuote.

type ClassModule 

type ClassModule struct {
	// IsModule distinguishes `module` from `class`.
	IsModule bool
	// Name is the simple (last-segment) name as written, e.g. "Bar" in
	// "class Foo::Bar".
	Name string
	// FullName is the qualified name including the lexical nesting.
	FullName string
	// Superclass is the parent class name for "class X < Y" (empty otherwise).
	Superclass string
	// Comment is the attached documentation comment (RDoc markup source).
	Comment   string
	Methods   []*AnyMethod
	Constants []*Constant
	Attrs     []*Attr
	Aliases   []*Alias
	// Nested holds classes and modules declared inside this one. Qualified
	// declarations like "class A::B" synthesize the intermediate module A and
	// nest B inside it, mirroring RDoc's namespace expansion.
	Nested []*ClassModule
}

ClassModule is a class or module declaration with its members. Mirrors RDoc::ClassModule (NormalClass / NormalModule).

type Constant 

type Constant struct {
	Name    string
	Value   string
	Comment string
}

Constant is a constant assignment. Mirrors RDoc::Constant.

type Document 

type Document struct {
	Parts []Element
}

Document is the root of the markup model, a sequence of block-level elements. It mirrors RDoc::Markup::Document.

func Parse 

func Parse(text string) *Document

Parse tokenizes and parses RDoc markup text into a Document. It is the public equivalent of RDoc::Markup::Parser.parse.

func (*Document) Accept 

func (d *Document) Accept(f Formatter)

Accept walks the document, invoking the formatter on each part. It is the public entry equivalent to RDoc::Markup::Document#accept.

type Element 

type Element interface {
	// contains filtered or unexported methods
}

Element is the interface implemented by every node in the markup document model. accept dispatches to the visitor (a Formatter).

type Formatter 

type Formatter interface {
	// contains filtered or unexported methods
}

Formatter is the public interface implemented by the output visitors (ToHtml, etc.). Document.Accept drives it.

type HTMLOptions 

type HTMLOptions struct {
	// OutputDecoration controls whether headings get id/anchor decoration
	// (RDoc::Options#output_decoration, default true).
	OutputDecoration bool
	// Pipe mirrors RDoc::Options#pipe (markdown-pipe mode): headings/verbatim
	// are emitted without anchors / highlighting.
	Pipe bool
	// Highlighter, if set, syntax-highlights a verbatim block that looks like
	// Ruby, returning (html, true). When nil or returning ok=false, verbatim is
	// emitted as a plain escaped <pre>. HighlightRuby is the built-in
	// implementation; the deterministic default leaves this nil so output is
	// a plain <pre> without needing a Ruby toolchain.
	Highlighter func(code string) (string, bool)
	// Parseable reports whether a verbatim block is valid Ruby and should be
	// highlighted. RDoc::Markup::ToHtml#parseable? evaluates the block with the
	// real Ruby parser, which cannot be reproduced without a Ruby toolchain, so
	// this is a host seam. When nil, verbatim blocks are never auto-detected as
	// Ruby (only blocks explicitly flagged via Verbatim format are highlighted).
	Parseable func(code string) bool
	// CrossRef, if set, resolves a bare name to a link target for
	// ToHtmlCrossref behaviour.
	CrossRef func(name string) (href string, ok bool)
}

HTMLOptions controls HTML rendering, mirroring the subset of RDoc::Options the ToHtml formatter consults.

func DefaultHTMLOptions 

func DefaultHTMLOptions() *HTMLOptions

DefaultHTMLOptions returns options matching the rdoc gem defaults.

type Heading 

type Heading struct {
	Level int
	Text  string
}

Heading is a section heading of a given Level (1-6 logically, clamped to 6 when rendered). Mirrors RDoc::Markup::Heading.

type List 

type List struct {
	Type ListType

	Items []*ListItem
	// contains filtered or unexported fields
}

List is a bullet/number/label/note list. Mirrors RDoc::Markup::List.

type ListItem 

type ListItem struct {
	Label []string
	Parts []Element
}

ListItem is one entry in a List. Label holds the label parts for LABEL/NOTE lists (nil for plain lists). Parts holds the nested block content. Mirrors RDoc::Markup::ListItem.

type ListType 

type ListType int

ListType identifies the kind of a List, mirroring RDoc::Markup::Parser's LIST_TOKENS. 

const (
	// ListBullet is an unordered "* item" / "- item" list (:BULLET).
	ListBullet ListType = iota
	// ListLabel is a "[label] text" list (:LABEL).
	ListLabel
	// ListLalpha is a lower-alpha "a. item" ordered list (:LALPHA).
	ListLalpha
	// ListNote is a "label:: text" list (:NOTE).
	ListNote
	// ListNumber is a numeric "1. item" ordered list (:NUMBER).
	ListNumber
	// ListUalpha is an upper-alpha "A. item" ordered list (:UALPHA).
	ListUalpha
)

func (ListType) String 

func (t ListType) String() string

String returns the RDoc symbol name for the list type (e.g. "BULLET").

type Paragraph 

type Paragraph struct {
	Parts []string
}

Paragraph is a run of text. Its Parts are the raw text lines (joined with a space). Mirrors RDoc::Markup::Paragraph.

type Raw 

type Raw struct {
	Parts []string
}

Raw is verbatim output passed through untouched. Mirrors RDoc::Markup::Raw.

type Rule 

type Rule struct {
	Weight int
}

Rule is a horizontal rule (---). Weight mirrors the dash-count-minus-two stored by RDoc::Markup::Rule.

type ToHtml 

type ToHtml struct {
	// contains filtered or unexported fields
}

ToHtml renders an RDoc markup document model to HTML. It mirrors RDoc::Markup::ToHtml.

func NewToHtml 

func NewToHtml(opts *HTMLOptions) *ToHtml

NewToHtml builds an HTML formatter with the given options (nil = defaults).

type ToMarkdown 

type ToMarkdown struct {
	// contains filtered or unexported fields
}

ToMarkdown is a Markdown output formatter.

func NewToMarkdown 

func NewToMarkdown() *ToMarkdown

NewToMarkdown creates a Markdown formatter.

type ToRdoc 

type ToRdoc struct {
	// contains filtered or unexported fields
}

ToRdoc is an RDoc-markup output formatter.

func NewToRdoc 

func NewToRdoc() *ToRdoc

NewToRdoc creates an RDoc-markup formatter.

type TopLevel 

type TopLevel struct {
	Name             string
	ClassesAndModule []*ClassModule
}

TopLevel is the root code object for one source file. Mirrors RDoc::TopLevel.

func Extract 

func Extract(fileName, source string) *TopLevel

Extract parses Ruby source into a TopLevel code object named after fileName. It is the focused equivalent of running RDoc::Parser::Ruby over one file.

type Verbatim 

type Verbatim struct {
	Parts []string
	// contains filtered or unexported fields
}

Verbatim is an indented literal/code block. Parts are the lines, each ending in a newline. Mirrors RDoc::Markup::Verbatim.

type Visibility 

type Visibility string

Visibility mirrors RDoc method/attribute visibility. 

const (
	// Public visibility (the default).
	Public Visibility = "public"
	// Private visibility (after a bare `private`).
	Private Visibility = "private"
	// Protected visibility (after a bare `protected`).
	Protected Visibility = "protected"
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.