RDoc::Generator::SolarFish
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'
= RDoc::Options.new
.setup_generator 'solarfish'
.files = ['input_file.rb']
.op_dir = 'output_dir'
.title = 'Page title'
.sf_htmlfile = 'output_file.html'
.sf_jsonfile = 'output_file.json'
.sf_prefix = '/url_prefix'
.sf_template = '/path/to/template.slim'
.sf_themes = ['/path/to/theme.yml']
.sf_filter_classes = '^Test.*'
.sf_filter_members = '^test_.*'
rdoc = RDoc::RDoc.new
rdoc.document
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
- The source code is licensed under MIT license.
- Fonts and syntax themes have their own licenses.