# RDoc - Ruby Documentation System

- GitHub: [https://github.com/ruby/rdoc](https://github.com/ruby/rdoc)
- Issues: [https://github.com/ruby/rdoc/issues](https://github.com/ruby/rdoc/issues)

<p align="center" class="rdoc-logo">
  <img src="rdoc-logo.svg" alt="RDoc" width="168" height="198">
</p>

## Description

RDoc produces HTML and command-line documentation for Ruby projects.  RDoc includes the `rdoc` and `ri` tools for generating and displaying documentation from the command-line.

## Generating Documentation

Once installed, you can create documentation using the `rdoc` command

```shell
rdoc [options] [names...]
```

For an up-to-date option summary, type

```shell
rdoc --help
```

A typical use might be to generate documentation for a package of Ruby source (such as RDoc itself).

```shell
rdoc
```

This command generates documentation for all the Ruby and C source files in and below the current directory.  These will be stored in a documentation tree starting in the subdirectory `doc`.

You can make this slightly more useful for your readers by having the index page contain the documentation for the primary file.  In our case, we could type

```shell
rdoc --main README.md
```

You'll find information on the various formatting tricks you can use in comment blocks in the documentation this generates.

RDoc uses file extensions to determine how to process each file.  File names ending `.rb` and `.rbw` are assumed to be Ruby source.  Files ending `.c` are parsed as C files.  Files ending `.rbs` are parsed as RBS signature files.  All other files are assumed to contain just Markup-style markup (with or without leading `#` comment markers).  If directory names are passed to RDoc, they are scanned recursively for C, Ruby, and RBS source files.

RBS files can document classes, modules, methods, attributes, and constants.  When RBS declarations match objects already documented from Ruby source, their comments and type signatures extend the existing documentation.

To generate documentation using `rake` see [RDoc::Task](https://ruby.github.io/rdoc/RDoc/Task.html).

To generate documentation programmatically:

```rb
require 'rdoc/rdoc'

options = RDoc::Options.new
options.files = ['a.rb', 'b.rb']
options.setup_generator 'aliki'
# see RDoc::Options

rdoc = RDoc::RDoc.new
rdoc.document options
# see RDoc::RDoc
```

You can specify the target files for document generation with `.document` file in the project root directory. `.document` file contains a list of file and directory names including comment lines starting with `#`. See [https://github.com/ruby/rdoc/blob/master/.document](https://github.com/ruby/rdoc/blob/master/.document) as an example.

## Writing Documentation

To write documentation for RDoc, place a comment above the class, module, method, constant, or attribute you want documented:

```rb
##
# This class represents an arbitrary shape by a series of points.
class Shape
  ##
  # Creates a new shape described by a +polyline+.
  #
  # If the +polyline+ does not end at the same point it started at the
  # first pointed is copied and placed at the end of the line.
  #
  # An ArgumentError is raised if the line crosses itself, but shapes may
  # be concave.
  def initialize polyline
    # ...
  end
end
```

### Markup Formats

RDoc supports multiple markup formats:

| Format | File Extensions | Default For |
|--------|-----------------|-------------|
| [RDoc](doc/markup_reference/rdoc.rdoc) | `.rdoc` | `.rb`, `.c` files |
| [Markdown](doc/markup_reference/markdown.md) | `.md` | None |
| RD | `.rd` | None |
| TomDoc | N/A | None |

**RDoc markup** is currently the default format for Ruby and C files. However, we plan to retire it in favor of Markdown in the future.

**Markdown** support is actively being improved. Once it reaches feature parity with RDoc markup, it will become the default format.

For standalone documentation files, we recommend writing `.md` files instead of `.rdoc` files.

**RD** and **TomDoc** are legacy formats. We highly discourage their use in new projects.

### Specifying Markup Format

**Per-file:** Add a `:markup:` directive at the top of a Ruby file:

```ruby
# :markup: markdown

# This class uses **Markdown** for documentation.
class MyClass
end
```

**Per-project:** Create a `.rdoc_options` file in your project root:

```yaml
markup: markdown
```

**Command line:**

```bash
rdoc --markup markdown
```

### Feature Differences

| Feature | RDoc Markup | Markdown |
|---------|-------------|----------|
| Headings | `= Heading` | `# Heading` |
| Bold | `*word*` | `**word**` |
| Italic | `_word_` | `*word*` |
| Monospace | `+word+` | `` `word` `` |
| Links | `{text}[url]` | `[text](url)` |
| Code blocks | Indent 2 spaces | Fenced with ``` |
| Cross-references | Automatic | Automatic |
| Directives (`:nodoc:`, etc.) | Supported | Supported |
| Tables | Not supported | Supported |
| Strikethrough | `<del>text</del>` | `~~text~~` |
| Footnotes | Not supported | Supported |

For complete syntax documentation, see:

- [RDoc Markup Reference](doc/markup_reference/rdoc.rdoc)
- [Markdown Reference](doc/markup_reference/markdown.md)

### Directives

Comments can contain directives that tell RDoc information that it cannot otherwise discover through parsing. See RDoc::Markup@Directives to control what is or is not documented, to define method arguments or to break up methods in a class by topic. See RDoc::Parser::Ruby for directives used to teach RDoc about metaprogrammed methods.

See RDoc::Parser::C for documenting C extensions with RDoc.

### Documentation Coverage

To determine how well your project is documented run `rdoc -C lib` to get a documentation coverage report. `rdoc -C1 lib` includes parameter names in the documentation coverage report.

## Theme Options

RDoc ships with two built-in themes:

- **Aliki** (default) - A modern, clean theme with improved navigation and search
- **Darkfish** (deprecated) - The classic theme, will be removed in v9.0

To use the Darkfish theme instead of the default Aliki theme:

```shell
rdoc --format darkfish
```

Or in your `.rdoc_options` file:

```yaml
generator_name: darkfish
```

There are also a few community-maintained themes for RDoc:

- [rorvswild-theme-rdoc](https://github.com/BaseSecrete/rorvswild-theme-rdoc)
- [hanna](https://github.com/jeremyevans/hanna) (a fork maintained by [Jeremy Evans](https://github.com/jeremyevans))

Please follow the theme's README for usage instructions.

## Live Preview Server

RDoc includes a built-in server for previewing documentation while you edit source files. It parses your code once on startup, then watches for changes and auto-refreshes the browser.

```shell
rdoc --server
```

This starts a server at `http://localhost:4000`. You can specify a different port:

```shell
rdoc --server=8080
```

Or use the Rake task:

```shell
rake rdoc:server
```

### How It Works

- Parses all source files on startup and serves pages from memory using the Aliki theme
- A background thread polls file mtimes every second
- When a file changes, only that file is re-parsed — the browser refreshes automatically
- New files are detected and added; deleted files are removed

**No external dependencies.** The server uses Ruby's built-in `TCPServer` (`socket` stdlib) — no WEBrick or other gems required.

### Limitations

- **Reopened classes and file deletion.** If a class is defined across multiple files (e.g. `Foo` in both `a.rb` and `b.rb`), deleting one file removes the entire class from the store, including parts from the other file. Saving the remaining file triggers a re-parse that restores it.
- **Full cache invalidation.** Any file change clears all cached pages. This is simple and correct — rendering is fast (~ms per page), parsing is the expensive part and is done incrementally.
- **No HTTPS or HTTP/2.** The server is intended for local development preview only.

## Bugs

See [CONTRIBUTING.md](CONTRIBUTING.md) for information on filing a bug report.  It's OK to file a bug report for anything you're having a problem with.  If you can't figure out how to make RDoc produce the output you like that is probably a documentation bug.

## License

RDoc is Copyright (c) 2001-2003 Dave Thomas, The Pragmatic Programmers. Portions (c) 2007-2011 Eric Hodel.  Portions copyright others, see individual files and LEGAL.rdoc for details.

RDoc is free software, and may be redistributed under the terms specified in LICENSE.rdoc.

## Warranty

This software is provided "as is" and without any express or implied warranties, including, without limitation, the implied warranties of merchantability and fitness for a particular purpose.
