Hi,
I would love to hear your opinion on the idea of “combining RDoc and RSpec to create testable documentation”. Let me explain:
Given you have several RDoc files like this one:
= Examples Some example code snippets. == Authentication Supported authentication methods: * HTTP basic authentication Example: Net::HTTP.start('www.example.com') do |http| req = Net::HTTP::Get.new('/secret-page.html') req.basic_auth 'account', 'password' response = http.request(req) end
-
These RDoc files are parsed and code-blocks followed by a certain keyword (like “Example:” are saved for step 3.
-
An HTML documentation based on the RDoc files is generated, just like you would create an RDoc task via Rake::RDocTask and run “rake rdoc”. Nothing special here.
-
The code-blocks extracted from the RDoc files will be made accessable to some RSpec tests and run to verify they actually work.
I know this might be a lot of work, but it would allow you to create a fairly decent documentation along with examples of code that actually work.
Also I don’t know if it’s the best idea, but it’s certainly worth starting a discussion. Separating code from documentation (and keeping the documentation up to date) is pretty difficult, so by combining both life might be a little easier.
I appreciate any comments, ideas and feedback. I’m not aware of approach to combine documentation and tested examples, so please let me know if I’m missing something.
Python's doctest is similar in form and function. There's a wealth of user experience that can be drawn from that project.
http://docs.python.org/library/doctest.html