Hacking

For hacking fork it from github:

$ git clone git://github.com/senchalabs/jsduck.git

JsDuck depends on json, RDiscount, and parallel; plus RSpec for tests, compass for compiling the stylesheets, and Sencha SDK tools for combining JavaScript files. Make sure you have these installed:

$ gem list

First smoke test. Run the testsuite:

$ cd jsduck
$ rake

If everything is green continue with some configuration. Copy an ExtJS 4 download inside template/extjs directory (you might just create a symlink if you wish so):

$ cp -r path/to/ext-4.0.7 template/extjs

Now create a file sdk-vars.rb inside the jsduck directory. Use the following template:

# path to Ext JS 4 build
EXT_DIR='/path/to/ext-4.0.7'
# where to output the docs
OUT_DIR='/path/to/ouput/dir'
# path to SDK (for developers at Sencha)
SDK_DIR='/path/to/SDK'
# path to Animator (for developers at Sencha)
ANIMATOR_DIR='/path/to/Animator'

These config options define the input and output directories for the ext4 rake task. Leave out the SDK_DIR option if you are not a Sencha developer. Now run the task:

$ rake ext4

This will generate a development/debug version of the docs app into the output directory you specified in sdk-vars.rb file. Open up the directory in your web browser and see if everything looks fine. (This task only creates the class documentation, don't worry about guides, examples, etc being missing, and the index page of api docs blank).

This rake task is most suitable when developing the JavaScript side of the app, as it only symlinks the files in template/ directory, allowing you to modify the files there and see the results by just refreshing the browser window (and not having to run the rake task again and again).

To generate a stand-alone version of documentation (which you could upload to some server), add export parameter to the rake task:

$ rake ext4[export]

This will combine and compress the javascript files using Sencha SDK Tools and does not create symlinks to the development directory.

For developing the Ruby side, try to please the unit tests.

If you are a Sencha developer, use the sdk and touch tasks instead to generate either extjs or touch docs from the corresponding branches in SDK repository.

Happy hacking.

Working on Windows

First get yourself some Ruby. For example visit rubyinstaller.org and grab the latest installer from the download page. Run it and make sure Ruby executable gets added to your PATH. You also need to install the development kit to be able to build native extensions - download it from the same site, then follow the installation instructions (be careful when using the self-extracting exe - if you don't give it a new directory name, it will unpack all files to the current directory, which you probably don't want).

Now you can finally install jsduck...

Building the gem file

Update JSDuck version number and release date in jsduck.gemspec and version number in jsduck/lib/options.rb. Then simply run the gem task:

$ rake gem

Upload the gem to RubyGems.org or whatever you please.

Building Windows executable

You need a working Ruby installation on your Windows machine and the ocra gem which is used for creating the actual .exe.

Install latest JSDuck:

gem install jsduck
# or from a local .gem file
gem install jsduck-3.0.gem

Try it out with builtin classes:

jsduck -o docs --verbose --builtin-classes

Locate the jsduck executable in gems directory and build it with ocra. Something like this:

ocra --gem-full C:\Ruby193\lib\ruby\gems\1.9.1\gems\jsduck-3.8.1\bin\jsduck

Test the executable.

jsduck.exe -o docs --verbose --builtin-classes

Rename to the correct version and upload to Github.