Hacking

(Updated for JSDuck 4.x)

For hacking fork it from github (if your really plan do develop, you should create your own fork in github and clone from that):

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

The master branch is for JSDuck 4.x development. 3.x development is no more actively happening.

Dependencies

JsDuck depends on json, RDiscount, parallel and therubyracer. Those you should already have if you have jsduck installed.

In development Rake is used for building, RSpec for tests, compass for compiling the stylesheets, and Sencha SDK tools for combining JavaScript files. The last one you need to download separately, the first three are just a gem-install away:

$ gem install rake rspec compass

Additionally JSDuck needs the build of Ext JS to be available in jsduck/template/extjs/. The simplest way to set it up is to run the configure script:

$ cd jsduck
$ rake configure

This will also generate a sdk-vars.rb config file which should be good enough for start.

First run

For first smoke test. Run the testsuite:

$ rake

If everything is green... well, happy days.

Now run the task:

$ rake ext4

This will generate a development/debug version of the documentation for Ext JS into the jsduck/output/ dir.

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).

Open up the directory in your web browser and see if everything looks fine.

Additional manual configuration

Here's an example of all the possible variables in the sdk-vars.rb config file:

# path to Ext JS 4 build
EXT_BUILD='/path/to/extjs-4.1.1'
# 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 Touch 2 build (for developers at Sencha when building Touch)
TOUCH_BUILD='/path/to/touch-2.0.1'

The last two options don't concern you if you're not working in Sencha.

But you'll likely want to change where the documentation gets written when you run the :ext4 task, or when you want to build docs for some other version of ExtJS than the one in jsduck/template/extjs dir.

If you are a Sencha developer, you should use the sdk and touch2 tasks instead to generate either extjs or touch docs from the corresponding branches in SDK repository. For that set up the appropriate variables in sdk-vars.rb.

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).

If you don't yet have git, get Git for Windows first. Then continue with the main hacking guide at the top of the page.

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

You can't push new versions of JSDuck into rubygems.org by yourself. See the "Contributing your changes" section below.

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

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-4.0.0\bin\jsduck

Test the executable.

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

Rename to the correct version and upload to your place of choice.

Contributing your changes

Please follow the coding style already established in existing Ruby, JavaScript and SCSS files.

Set your editor to trim trailing spaces or do it manually.

In JavaScript use Ext.Array.forEach instead of a for loop, unless you can demonstrate considerable performance benefit of the latter in particular case. Multiple var statements should be preferred to one long var at the beginning of a function. And use some linting tool to unsure you have no trailing commas or missing semicolons.

Each class and every public method in it must have a doc-comment /** */. A public method is any method that is called or meant to be called from outside the class itself. Other methods may be also commented, but if you comment them with doc-comment, include @private tag. Also, try to comment your CSS. In Ruby just make sure you document the public methods, use the private keyword to distinguish others.

Format your commit messages with a well established convention of short summary line + longer description. For example, follow this guide: A Note About Git Commit Messages. If you change multiple things, do multiple commits. In general more granular commits are preferred, but if it's just one large change, it's fine having it as one large commit.

Last, but not least, you need to sign the Sencha Contributor License Agreement - otherwise we won't accept your code into this SenchaLabs project. (It basically gives Sencha rights to use your contributions however it pleases.)