What is sdoc?
SDoc is an HTML template built on top of the RDoc documentation generator for Ruby code.
# Install the gem gem install sdoc # Generate documentation for 'projectdir' sdoc projectdir
sdoc is simply a wrapper for the
rdoc command line tool. See
sdoc --help for more details.
When using the
--fmt is set to
shtml by default. The default template (or
-T option) is set to
shtml, but you can also use the
direct template when generating documentation.
sdoc -o doc/rails -T direct rails
If you want, you can setup a task in your
Rakefile for generating your project's documentation via the
rake rdoc command.
# Rakefile require 'sdoc' # and use your RDoc task the same way you used it before require 'rdoc/task' # ensure this file is also required in order to use `RDoc::Task` RDoc::Task.new do |rdoc| rdoc.rdoc_dir = 'doc/rdoc' # name of output directory rdoc.options << '--format=sdoc' # explictly set the sdoc generator rdoc.template = 'rails' # template used on api.rubyonrails.org end
NOTE: If you don't set
template the default "sdoc" template is chosen, with a lighter color scheme.
Now you can execute this command with
rake rdoc, to compile the documentation for the current project directory.
Alternatively you can pass this command a path to the project you wish to compile:
rake rdoc path/to/project.
As mentioned before, SDoc is built on top of the RDoc project.
If you notice any bugs in the output of your documentation, it may be RDoc's fault and should be reported upstream.
An example of an SDoc bug would be:
- Generation fails with some exception (likely due to incompatibility with RDoc)
Please feel free to still report issues here for both projects, especially if you aren't sure. We will try to redirect to the proper place if necessary.
If you'd like to contribute you can generate the Rails main branch documentation by running:
You can generate the Ruby default branch documentation by running:
The generated documentation will be put into
To view the just generated documentation start up a rack application by running:
Then open http://localhost:9292 in the browser to view the documentation.
- Vladimir Kolesnikov (voloko)
- Nathan Broadbent (ndbroadbent)
- Petrik de Heus (p8)