Publishing Your Documentation

Credit: Stefan Lang

Problem

You want to automatically update your projects web site on RubyForge (or some other site) with generated documentation or custom pages.

Solution

As seen in Recipe 19.2, Rake provides a RDocTask for generating RDoc documentation:

	require 
ake/rdoctask

	html_dir = doc/html
	library = MyLib
	Rake::RDocTask.new(
doc) do |t|
	 t.rdoc_files.include(README, lib/**/*.rb)
	 t.main = README
	 t.title = "#{library} API documentation"
	 t.rdoc_dir = html_dir
	end

To upload your generated documentation to RubyForge, use this task along with the upload-docs task defined below. The Unix scp command-line tool does the actual work of uploading:

	# Define your RubyForge username and your projects Unix name here:
	rubyforge_user = user
	rubyforge_project = project
	rubyforge_path = "/var/www/gforge-projects/#{rubyforge_project}/"
	desc Upload documentation to RubyForge.
	task upload-docs => [
doc] do
	 sh "scp -r #{html_dir}/* " +
	 "#{rubyforge_user}@rubyforge.org:#{rubyforge_path}"
	end

Discussion

Set off the publishing process by invoking rake upload-docs. The upload-docs task has the rdoc task as a prerequisite, so the HTML pages under doc/html/ will be created if necessary.

Then scp prompts for your RubyForge account password. Enter it, and all files under doc/html/ and its subdirectories will be uploaded to RubyForge. The docs will become available under http://project.rubyforge.org/, where "project" is the Unix name of your project. Now your users can read your RDoc online without having to generate it themselves. Your documentation will also show up in web search results.

Rakes sh method starts an instance of the OSs standard shell. This feature is used to run the scp command-line tool. This means that this recipe will only work if scp is installed on your system.

The scp command copies all the files that the RDoc placed under doc/html/, to the root of your projects web site on the RubyForge server. In effect, the main page of the API documentation will appear as your projects homepage. Some RubyForge projects don have a custom homepage, so this is a good place to put the RDoc. If you want a custom homepage, just copy the RDoc into a different directory by changing rubyforge_path:

	rubyforge_path = "/var/www/gforge-projects/#{rubyforge_project}/rdoc/"

Youll have to manually create the rdoc directory before you can use the scp shortcut. After that, the generated RDoc will show up at http://project.rubyforge.org/rdoc/, and you can link to it from your custom homepage with a relative link to rdoc/.

You can make Rake upload your custom homepage as well, of course. Just add an upload-site task that uploads your custom homepage and other web content. Make upload-site and upload-docs prerequisites of an overarching publish task:

	website_dir = site
	desc Update project website to RubyForge.
	task upload-site do
	 sh "scp -r #{website_dir}/* " +
	 "#{rubyforge_user}@rubyforge.org:/var/www/gforge-projects/project/"
	end

	desc Update API docs and project website to RubyForge.
	task publish => [upload-docs, upload-site]

Now you can run rake publish to update the generated API documentation, and upload it together with the rest of the web site to RubyForge. The publish task can be just one more prerequisite for an overarching release task.

Of course, you can use this same technique if you e using a web host other than RubyForge: just change the destination host of the scp command.

See Also

• Recipe 17.11, "Documenting Your Application," covers writing RDoc documentation
• Recipe 19.2, "Automatically Generating Documentation"