Rake tasks for Rails Guides

rubyonrails-docs
1

Hi,

I added some content in the ActiveRecord Validations and Callbacks guide yesterday.

After doing the necesarry changes I compiled only that file by running

rake generate_guides ONLY=active_record_validations_callbacks WARNINGS=1

The first few times the rake task errored because of missing gems (if I remember correctly) and an empty HTML output file was generated. When running it again I was having the issue that the file wouldn't be overwritten and it was kept empty.

It wasn't until I had all dependency gems install and *I deleted the file* that the rake task generated the HTML properly. If this is the expected behaviour maybe we could add a notice in the instructions so people know about this.

The second problem I ran to was using the validator rake task. The output is very long but not very informative:

[alberto@alberto-macbook:~/Code/other/docrails/railties/guides → master]$ rake validate_guides (in /Users/alberto/Code/other/docrails/railties) /Users/alberto/.rvm/rubies/ruby-1.9.2-p180/bin/ruby guides/ w3c_validator.rb E

There are 1 guides with validation errors:

  ./guides/output/active_record_validations_callbacks.html

Here are the detailed errors for each guide:

  ./guides/output/active_record_validations_callbacks.html has 74 validation error(s):

    ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line     ERROR; URI: ./guides/output/ active_record_validations_callbacks.html; line

Am I doing something wrong or is it the expected behaviour? If is the latter, maybe we could improve it?

Cheers! Alberto.

2

That’s a problem with the latest version of the w3c_validators gem. It should be fine if you use version 1.0.2, you’ll get a detailed error report.

Don’t get too obsessed with markup validation of the guides, it’s a nice to have but not a must. Right now, almost every guide has markup validation errors, mostly due to the tag:

http://w3clove.com/check/edgeguides.rubyonrails.org

3

Hi Jaime,

That's a problem with the latest version of the w3c_validators gem. It should be fine if you use version 1.0.2, you'll get a detailed error report.

Thanks for the info. I'll try that version.

Don't get too obsessed with markup validation of the guides, it's a nice to have but not a must. Right now, almost every guide has markup validation errors, mostly due to the <notextile> tag: http://w3clove.com/check/edgeguides.rubyonrails.org

I know it's not mandatory but I didn't want to introduce new validation errors at least.

Thanks Jaime!