RDoc

RDoc generates HTML documentation and command-line reference material for Ruby projects. The `rdoc` tool creates documentation, and `ri` displays it. It processes Ruby, C, and RBS source files, along with RDoc markup, Markdown, RD, and TomDoc documents. RBS declarations can describe classes, modules, methods, attributes, and constants, and can add comments and type signatures to documentation for corresponding Ruby source. For local development, an included preview server watches source files and refreshes the browser when they change. It uses Ruby's built-in TCPServer and needs no external gems. RDoc can report project documentation coverage with `rdoc -C`; `rdoc -C1` includes parameter names. Documentation can be generated through a Rake task or the RDoc API. The Aliki theme is included by default; the classic Darkfish theme is deprecated and slated for removal in v9.0. RubyGems lists Ruby 3.2.0 or newer as required for the current gem. RDoc is free software, with no paid plans or usage limits stated, and is provided without express or implied warranties.

RDoc provides source-driven documentation generation, a local preview server, and coverage reporting at no stated cost. Users should note the Ruby version requirement and the preview server's local-only scope.

RDoc suits Ruby project maintainers who want to generate HTML or command-line documentation from source and markup. Its preview server is intended for local development rather than network-facing use.

RDoc is a free documentation generator for Ruby projects, producing browsable HTML and command-line references through its rdoc and ri tools. It is best for Ruby teams that want source-aware API documentation, RBS-aware signatures, and a buildable local workflow. Its no-cost coverage and automation are compelling, provided you can work with Ruby 3.2 or newer and do not need a remotely secure preview site.

Overview

RDoc processes Ruby and C source, RBS declarations, and standalone markup, then emits HTML or RI output. That combination suits libraries and applications where API reference should stay close to implementation comments and type information. RBS can document classes, modules, methods, attributes, and constants, while also extending matching Ruby documentation with signatures.

For prose, RDoc accepts RDoc markup, Markdown, RD, and TomDoc. Markdown is the sensible choice for new standalone material; RD and TomDoc are discouraged for new projects. The included Aliki theme is the forward-looking default, while the classic Darkfish theme is deprecated and scheduled for removal in version 9.0.

Key features

Coverage and source-aware references

rdoc -C reports documentation coverage, and rdoc -C1 includes parameter names. Those reports give maintainers a concrete way to find undocumented areas instead of relying on a subjective scan of generated pages. RBS support is particularly useful when a project maintains typed interfaces alongside Ruby implementation files.

Live local preview

The preview server watches source files and refreshes the browser after changes. It uses Ruby's built-in TCPServer, so it needs no external gems, WEBrick, or other server dependency. That keeps setup lean for local authoring, but it is not a deployment server: there is no HTTPS or HTTP/2, and the feature is intended only for local development. A further edge case affects reopened classes: deleting a file that contributes to a class spread across several files can temporarily remove the whole class from the preview store until another file is saved and reparsed.

Automation and integration

Documentation generation can run from a Rake task or through RDoc's Ruby API, making it suitable for CI/CD pipelines and repeatable release builds. The output choices, HTML and RI, cover published reference pages and terminal-oriented lookup without requiring a separate documentation service.

Pricing

There is no trial because the software is free, and no seat, quota, or renewal charge is stated. It may be redistributed under its license, but it comes without express or implied warranties. RubyGems lists Ruby 3.2.0 or newer as required for the current gem.

Platforms

RDoc targets Linux and self-hosted environments. It is a strong match for teams comfortable installing and running Ruby tooling in their own repositories or build systems, rather than buyers seeking a hosted documentation workspace.

Who it's for

Choose RDoc for Ruby libraries and applications that need API reference generated from Ruby, C, or RBS sources, plus Markdown-based guides and a local authoring loop. It also fits teams that want coverage checks and scripted generation in Rake or CI/CD. Look elsewhere if you need a browser-hosted service, secure remote preview, or documentation centered on another language ecosystem.

Pros and cons

Pros

• Free with no stated usage caps: the complete workflow costs $0.
• Ruby- and RBS-aware output: comments, signatures, and declarations can contribute to one API reference.
• Useful quality signal: coverage reports expose documentation gaps and can include parameter names.
• Lean automation: Rake and the Ruby API support repeatable builds without external preview-server gems.

Cons

• Local-only preview: absent HTTPS and HTTP/2 make it unsuitable for public or shared staging.
• Ruby version floor: the current gem requires Ruby 3.2.0 or newer.
• Preview-store edge case: deleting one file in a reopened class can temporarily hide the entire class.
• Theme transition: Darkfish is deprecated and will be removed in v9.0.

Alternatives

Sphinx is the better pick for a broad, self-hosted documentation system spanning multiple platforms and formats under the BSD 2-Clause license. JSON Schema for Humans fits projects whose input is JSON Schema and whose target is static HTML or Markdown. TypeDoc is the direct alternative for TypeScript documentation.

Asciidoctor is preferable when open-source AsciiDoc conversion to HTML 5, DocBook 5, and man pages is the priority. Scalar suits API teams wanting a hosted or self-hosted API workspace with a free tier and paid collaboration limits. Swift Package Manager is the relevant free choice for Swift package management rather than Ruby documentation.

Sandcastle Help File Builder targets Windows users who want a standalone GUI, command-line tools, Visual Studio integration, and MSBuild tasks. StepShot is a macOS capture-and-edit tool with Markdown and HTML export, not a source-code API generator.

For a wider comparison, see Documentation Generators.

Verdict

RDoc is the right choice for Ruby developers who want free, source-aware API documentation, RBS support, coverage reporting, and scriptable generation inside their own toolchain. Choose another product when your audience needs a hosted, remotely accessible preview or when your project is centered on TypeScript, JSON Schema, Swift, or general-purpose prose conversion.