RDoc::Generator::SolarFish Gem Version Build Status

Single-page HTML5 generator for Ruby RDoc.

Features

  • Generate single-page HTML5 documentation suitable for offline use.
  • Templates support using Slim.
  • Themes support.
  • Out of the box Sass and SCSS support.
  • Filter classes or members by regex.

Example

See example output:

It was generated from the example.rb in the docs directory.

Generate locally:

$ rake install
$ rake example

Installation

From rubygems:

$ gem install rdoc-generator-solarfish

From sources:

$ rake install

Usage

From command line

Display all supported command line options:

$ rdoc --help

Generate documentation under the doc/ directory:

$ rdoc -f solarfish --title "My Project"

Use custom directory and file name:

$ rdoc -f solarfish --output superdoc --sf-htmlfile superdoc.html

Additionally dump JSON:

$ rdoc -f solarfish --output superdoc --sf-htmlfile superdoc.html --sf-jsonfile superdoc.json

Specify template name:

$ rdoc -f solarfish --sf-template onepage

Specify theme name:

$ rdoc -f solarfish --sf-theme light

Specify additional theme that may partially override default one:

$ rdoc -f solarfish --sf-theme light --sf-theme ./custom_theme.yml

Filter classes and members by regex:

$ rdoc -f solarfish --sf-filter-classes '^Test.*' --sf-filter-members '^test_.*'

From code

require 'rdoc/rdoc'

options = RDoc::Options.new
options.setup_generator 'solarfish'

options.files = ['input_file.rb']
options.op_dir = 'output_dir'
options.title = 'Page title'

options.sf_htmlfile = 'output_file.html'
options.sf_jsonfile = 'output_file.json'

options.sf_prefix = '/url_prefix'

options.sf_template = '/path/to/template.slim'
options.sf_themes = ['/path/to/theme.yml']

options.sf_filter_classes = '^Test.*'
options.sf_filter_members = '^test_.*'

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

Configuration

Templates

The HTML page layout is defined by a Slim template.

Only one template is available out of the box:

You can configure what template to use with the --sf-template option. Its value may be either a path or a name. In the later case, the template is searched in all locally installed gems that provide data/rdoc-generator-solarfish/templates directory.

Themes

The HTML page style is defined by a YAML theme. A theme file may contain Sass and SCSS stylesheet files and font files.

Only one theme is available out of the box:

You can configure what theme to use with the --sf-theme option. Its value may be either a path or a name. In the later case, the theme is searched in all locally installed gems that provide data/rdoc-generator-solarfish/themes directory.

Multiple themes can be used simultaneously. In this case, each next theme may add more stylesheet or font files and overrides previous themes.

Development

Install development dependencies:

$ bundle

Run tests:

$ rake test

Run linters:

$ rake rubocop

Automatically fix some linter errors:

$ rake rubocop:auto_correct

License