Clone this wiki locally
(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
master branch is for JSDuck 4.x development. 3.x development is no
longer actively happening.
$ gem install rake rspec compass compass-blueprint
Additionally JSDuck needs the build of Ext JS to be available in
The simplest way to set it up is to run the configure script (*Note configure does not work on Windows - examine configure task in rakefile to ensure you have the correct version of ExtJs):
$ cd jsduck $ rake configure
This will also generate a sdk-vars.rb config file which should be good enough for start.
For first smoke test. Run the testsuite:
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
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
If you are a Sencha developer, you should use the
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.
Working on Windows
Follow the Installation guide to install JSDuck through rubygems - this way you get Ruby and all the JSDuck dependencies.
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 by running:
$ rake bump
$ rake bump["3.2.1"]
The first one will automatically increment the patch version number, the second one will let you set any version number you want. This will also commit the change and tag it with the same version number. Version numbers should follow to the [Semantic Versioning guidelines].
To generate the gem you first need to have a JSDuck-built documentation app available at
http://localhost/docs/ (you can go and change this hardcoded URL in
Rakefile to point at your own preferred location). Then run:
$ rake gem
You can't push new versions of JSDuck into rubygems.org by yourself. See the "Contributing your changes" section below. You can however install the gem locally like so:
$ gem install jsduck-X.XX.X.gem
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
Set your editor to trim trailing spaces or do it manually.
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 ensure 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 also be 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.)