How To Update RDOC and Submit Patches - Watir

Instructions for volunteers who would like to update the Watir RDOC.

These instructions assume you already have ruby installed. They also assume you want to use (and don't have) the Eclipse IDE to edit the RDOC and to access the watir subversion repository. You are of course welcome to access subversion and edit the RDOC in any way you like.

Set up Eclipse:

Download Eclipse: http://www.eclipse.org/downloads/
Unzip the Eclipse zip file into 'C:\Program Files\eclipse'.
Zip file contains just another folder called 'eclipse' that has the executable and subdirectories
Open Eclipse and Choose 'Help -> Software Updates -> Find and Install'
In the dialog choose "Search for new features to install" and click Next.
Select "Add Remote Site" and add http://updatesite.rubypeople.org/release for release builds.
Check RDT and push next.
Select the feature 'org.rubypeople.rdt' and push next. RDT will be installed and be available after restart.
Click on "Add Remote Site" and add http://subclipse.tigris.org/update_1.2.x for the Subclipse plugin. This version is for Eclipse 3.2 and up. Use http://subclipse.tigris.org/update_1.0.x for older versions of Eclipse, or upgrade Eclipse itself.
Go to the Installed Interpreters preference page by selecting 'Ruby -> Installed Interpreters' in the tree pane on the left. Click the Add button to define the location of your ruby executable (e.g. 'C:\ruby\bin\ruby.exe'). A dialog opens where you can specify a name and the path to a ruby interpreter. The name can be chosen freely, but for convenience use 'Ruby Interpreter'.
Start eclipse (e.g. 'C:\Program Files\eclipse\eclipse\eclipse.exe', depending on where you put it). Feel free to create a shortcut from your desktop.
If you don't have a default workspace set yet, you will be prompted to create one (e.g. 'C:\dev').

Import latest watir code from subversion repository:

Go to 'File -> Import'.
Select 'Other -> Checkout Projects from SVN' and click Next.
Select 'Create a new repository location' and click Next.
Set Url: 'https://svn.openqa.org/svn/watir/trunk/watir' and click Next.
Select Watir and click Next.
Select Head Revision and click Next.
Check 'Use default workspace location' and click Finish.

Edit the rdoc content:

The rdoc is generated from comments within watir.rb. Editing the comments will result in changes to the rdoc when you next generate it. For example, to add ':class' to the list of elements we can use to access a button, I simply inserted the following comment to the comments immediately above the definition for button:

#    :class      - finds the item using the class attribute

Generate the rdoc with rake:

From the command prompt, navigate to the folder containing watir (e.g. 'C:\dev\watir').

Type 'rake rdoc'. You should see something like:

C:\dev\watir>rake rdoc
(in C:/dev/watir)
rm -r rdoc

                           watir.rb: c.c.c..m..c.c.c....m.m.......................................................c.....m........c....................
...............................................c..c..c............................c..c....c.........c.......m....c.c........c....ccccc..cc............
.....c.....c.....c.....c.....c............c......c..c.........m...c.c...cc..........c....c.c......cc..m..cc......c...c...c...c...c..c...c..ccc..c..c..
.c..c..c...c..c..c...c..c..c..c......
                          readme.rb: c
Generating HTML...

Files:   2
Classes: 67
Modules: 7
Methods: 377
Elapsed: 6.828s

This will create a new rdoc folder in the same directory that you are in.

To confirm that your rdoc was created correctly, open the new rdoc in a browser (e.g. 'file:///C:/dev/watir/rdoc/index.html').

Wrap your changes into a patch file with subclipse:

Instructions here:

http://svn.collab.net/subclipse/help/index.jsp?topic=/org.tigris.subversion.subclipse.doc/html/reference/create-patch.html

When you have generated your patch, save it and attach it to an appropriate Jira ticket for tracking.