RDoc produces HTML and online documentation for Ruby projects. RDoc includes the rdoc and ri tools for generating and displaying online documentation.
Ruby JavaScript HTML CSS
Latest commit f191513 Jul 14, 2016 @zzak zzak committed on GitHub Merge pull request #406 from jeremyevans/frozen-string-comment
Ignore frozen_string_literal magic comment (Fixes #389)
Permalink
Failed to load latest commit information.
bin Handle running out of space Nov 27, 2012
lib Merge pull request #406 from jeremyevans/frozen-string-comment Jul 14, 2016
test Ignore frozen_string_literal magic comment (Fixes #389) May 24, 2016
.autotest Enable warnings in autotest (like rake test) Nov 25, 2014
.document Import various improvements from Thierry Lambert. See History.txt. Sep 10, 2010
.gitignore Replaced hoe plugins including for generating parsers with plain Ruby Mar 19, 2016
.travis.yml Merge branch 'master' of github.com:rdoc/rdoc into no-hoe Jul 14, 2016
CONTRIBUTING.rdoc Document `rake` and `rake clean` commands to generate and delete RDoc Nov 13, 2013
CVE-2013-0256.rdoc Fix CVE-2013-0256, an XSS exploit in RDoc Feb 6, 2013
ExampleMarkdown.md Improve wording in markup output examples Jul 9, 2013
ExampleRDoc.rdoc Improve wording in markup output examples Jul 9, 2013
Gemfile Replaced hoe plugins including for generating parsers with plain Ruby Mar 19, 2016
History.rdoc Revert "Revert "History"" May 22, 2016
LEGAL.rdoc s/Sdoc/SDoc [ci skip] Mar 25, 2016
LICENSE.rdoc Convert LICENSE to rdoc Sep 23, 2011
Manifest.txt Include lib/rdoc/generator/pot/* in built gem Feb 5, 2016
README.rdoc Add build status icon to README Mar 16, 2016
RI.rdoc Rename txt documentation files to "rdoc" Sep 29, 2011
Rakefile Merge branch 'master' of github.com:rdoc/rdoc into no-hoe Jul 14, 2016
TODO.rdoc Update TODO from accessibility call Dec 26, 2013
rdoc.gemspec Fix travis failures 💣 Mar 19, 2016

README.rdoc

RDoc - Ruby Documentation System

home

github.com/rdoc/rdoc

rdoc

docs.seattlerb.org/rdoc

bugs

github.com/rdoc/rdoc/issues

build status

Build Status

code quality

code climate

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

$ rdoc [options] [names...]

For an up-to-date option summary, type

$ rdoc --help

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

$ 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

% rdoc --main README.rdoc

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. 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 and Ruby source files only.

To generate documentation using rake see RDoc::Task.

To generate documentation programmatically:

gem 'rdoc'
require 'rdoc/rdoc'

options = RDoc::Options.new
# see RDoc::Options

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

Writing Documentation

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

##
# 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

The default comment markup format is the RDoc::Markup format. TomDoc, Markdown and RD format comments are also supported. You can set the default comment format for your entire project by creating a .rdoc_options file. See RDoc::Options@Saved+Options for instructions on creating one. You can also set the comment format for a single file through the :markup: directive, but this is only recommended if you wish to switch markup formats. See RDoc::Markup@Other+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.

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.

Bugs

See CONTRIBUTING@Bugs 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 © 2001-2003 Dave Thomas, The Pragmatic Programmers. Portions © 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.