Generate Browsable Ruby Docs with rdoc3.2

A Ruby project with no generated docs is fine until someone else needs to read it: rdoc3.2 fixes that fast. It turns your source into a browsable HTML reference, or RI data for Ruby's ri tool, in a few minutes. HTML is the safer first target because it stays inside your project workspace.

Allow five to fifteen minutes depending on the project. This machine provides RDoc 6.5.0 through Ruby 3.2.3. The installed command is rdoc3.2; rdoc is its unversioned alias, and the local manpage documents the same interface for both names.

Do not run this against a source tree you have not inspected. RDoc parses Ruby files and walks directories, so the names you give it decide the scope of the scan.

1. Confirm the version and project layout

Start with read-only checks:

$ command -v rdoc3.2
/usr/bin/rdoc3.2
$ rdoc3.2 --version
6.5.0
$ find lib -maxdepth 2 -type f -name '*.rb' -print | sort
lib/example/client.rb
lib/example/version.rb

Use lib, app or another explicit source directory below; the command also accepts individual Ruby files. Omit all names and RDoc processes every Ruby file in the current directory and its subdirectories, generated or vendored code included.

2. Generate HTML into a clean directory

Choose the HTML formatter with -f html and the destination with -o. The long forms are --fmt and --op:

$ rm -rf -- doc/rdoc
$ rdoc3.2 \
    --fmt html \
    --op doc/rdoc \
    lib

Warning: that removal is only safe when doc/rdoc is definitely a generated directory. RDoc can replace files at the destination, so check the path first. Want to keep an earlier set of docs? Use a new directory instead.

RDoc parses the named files before writing output, so it can resolve cross-references across the project. A successful run normally prints progress and returns status zero, but check the actual result rather than trusting the last terminal line:

$ test -f doc/rdoc/index.html && echo 'HTML documentation generated'
HTML documentation generated
$ find doc/rdoc -maxdepth 2 -type f -print | sort | head
doc/rdoc/Example.html
doc/rdoc/_index.html
doc/rdoc/index.html

Exact filenames depend on the classes and modules in your source. The index is the real checkpoint: open it locally and confirm the project names and public methods you expected are actually there.

3. Control what RDoc includes

RDoc documents public methods by default. Add --all when private and protected methods belong in the reference:

$ rdoc3.2 --fmt html --op doc/rdoc-all --all lib

Use --exclude to skip matching files or directories:

$ rdoc3.2 \
    --fmt html \
    --op doc/rdoc \
    --exclude 'test|vendor|tmp' \
    .

Explicitly named files are not excluded by a pattern, so keep the command readable: either name the source directory and exclude distractions, or name the small set of files you actually want documented. Do not reach for --all just to make the output look bigger; private implementation details can make a public API harder to use, not easier.

4. Use the other output modes

The manpage lists html, ri, xml and chm as formatters. HTML is selected explicitly above. For local RI data, use --ri with a project-owned output directory:

$ rdoc3.2 --ri --op doc/ri lib
$ find doc/ri -maxdepth 2 -type f -print | head

Plain --ri stores documentation under your home directory unless --op overrides it, which can surprise you in a build job. Specify the output directory whenever reproducibility matters.

Warning: --ri-site and --ri-system write site-wide or system-level data and need elevated privileges. Use them only when you deliberately want the documentation available to other users or as part of a Ruby installation, and never against an unreviewed source tree: the privilege changes where the data is installed, not how trustworthy the parsed code is.

5. Recover from bad or stale output

Old classes still showing up? Remove only the known output directory and regenerate. Parsing failed? Read the first reported filename and line number, fix the Ruby source or narrow the input list, then run the same command again. Keep a failed output directory only if it holds useful evidence, otherwise start clean.

Checkpoint: the job is done when the command returns zero, the output directory holds an index or the expected RI data, and the generated pages describe the source revision you meant to publish. RDoc output is derived data, so it can always be regenerated after a source change.

Done means