Getting Started With Stdlib-Doc

Is This Software For You?

This software is not supposed to be used by many people! It is used to generate HTML documentation and status reports. Wouldn‘t you rather download these or view them online rather than generate them yourself? If so, go to www.ruby-doc.org/stdlib/index.html.

What You Can Expect From the Software

Generated Documentation

You tell the software where to find the Ruby source code, and it has a list of packages in the standard library that it wants to document. It will run rdoc on each of these, collecting the results in a directory of your choice. It will also generate some ‘packaging’ files, like table of contents and overview.

The results of this can be seen at www.ruby-doc.org/stdlib/index.html.

Status Reports

The documentation that gets generated obviously doesn’t come from nowhere. rdoc collects comments from source code and turns it into cross-referenced documentation. Adding comments to Ruby’s standard library for this purpose is a volunteer effort. Now that we have a decent collection of documentation, it has become important to keep track of progress. Running a status report involves selecting a type of report, piping it through less, and squinting to make out the important information.

Mercifully, status reports are generated along with the documentation, so they can be examined more easily.

Dependencies

The software itself has an unavoidable dependency on ‘extensions’ (extensions.rubyforge.org). If you want to build tarballs, generate RDoc for the software, etc., you should have ‘rake’ (rake.rubyforge.org) as well.

Necessary Configuration

You must edit etc/cfg/stdlib-doc.yaml in order to specify the Ruby base directory and the documentation output directory. It will guess where to put the generated documentation if necessary, but it can’t guess where your Ruby source base is located, and without knowing that, it can’t generate any documentation.

The default location for generated documentation is html. The default config file overrides this to stdlib for packaging purposes.

Where and How to Run the Stdlib-Doc Software

This project is designed to be run directly from its CVS checkout directory. It is not "installed", and it is not distributed (i.e. you must get it via CVS). The reason for this is that it is heavily dependent on its two databases, status.yaml and gendoc.yaml, and you need CVS to keep these up to date.

From the root directory, run:

  $ ruby stdlib-doc.rb
  [message that tells you to specify status or gendoc]

  $ ruby stdlib-doc.rb status --help
  [help on getting status reports]

  $ ruby stdlib-doc.rb gendoc --help
  [help on generating documentation]

The help provided by the commands should be sufficient.

One way to generate all the documentation is this:

  $ rake gendoc

A Quick Overview of the Package

In the root directory of the package, there are the following files and directories:

stdlib-doc.rb: The front-end program. Takes one argument - status or gendoc - and defers to code within StdlibDoc.
StdlibDoc/: Most of the Ruby code is located under here. The directory/file hierachy mostly mirrors the module/class hierachy.
etc/cfg/stdlib-doc.yaml: The configuration file for the package, specifying the locations of the Ruby source and the intended documentation output, among other optional things.
data/gendoc.yaml: The database of documentation targets (base64, benchmark, …, yaml).
data/status.yaml: The database of library files and their documentation status.
doc/*.txt: Documents like this one.
doc/rdoc/: Location of stdlib-doc API documentation, if you generate it with rake rdoc.
etc/releases/: Where tarballs and zip files end up when they are generated by rake release.
etc/website/: Contains index.html for stdlib-doc.rubyforge.org.
etc/test_data: Data for unit testing. The tests themselves are mixed in with the actual source code.
html/: The default location for generating standard library documentation if you don’t specify it in cfg/stdlib-doc.yaml.
Rakefile: Contains commands to generate RDoc, package the documentation, upload it, and more.
VERSION: Contains a version identifier for the generated documentation, not for this software. This software is versionless, since it is never released.

GettingStarted.txt