What am I talking about? I’ll use the work I’m currently doing for my client to illustrate. We have a rails RDOC oriented README_FOR_APP page that has includes for things like change log, metrics, notes/todos and the like. These elements are built by our cruise control process (we simply added a few extra statements in the rake file that cruse fires off).
Ok so how hard is this to do?

The answer is it is very simple. Here is the blow by blow…

1. set you project up to run under cruise control.

2. By default, cruise wants to run your rake test task. So you need to create a new super task for cruise to run. In you project Rakefile, add a new build task to run your tests and then generate the documentation.

3. Edit your doc/README_FOR_APP with useful information. When you want to include some of the generated files like the changelog, you simply add :include:filename. As an example, here is the project readme file…

= Some Project - Prototype
You can visit the current prototype by going to our
demo [http://url.to.the.site/] site.

== Notes

:include:notes.txt

== Statistics

:include:stats.txt

(LOC = Lines of Code)

== CHANGELOG

:include:CHANGELOG

Pretty simple…

4. Modify cruise to use your new rake task.

5. Set up a symlink in project facing web server directory to point to your cruise directory. For example in ~dhainlin/public_html I did something like ln -s /var/cruise/cruisecontrolrb-1.2.1/projects/sample/work sample which created a directory called sample. This essentially creates a permalink for your project documentation.

6. Browse to your new docs and enjoy fresh, always current information.

Hope this is useful. If you have questions or problems, let me know.